C++ Module: thrusterDynamicEffector

Executive Summary

Thruster dynamics class used to provide thruster effects on body. This class is used to hold and operate a set of thrusters that are located on the spacecraft. It contains all of the configuration data for the thruster set, reads an array of on-time requests (double precision in seconds). It is intended to be attached to the dynamics plant in the system using the DynEffector interface and as such, does not directly write the current force or torque into the messaging system. The nominal interface to dynamics are the dynEffectorForce and dynEffectorTorque arrays that are provided by the DynEffector base class. There is technically double inheritance here, but both the DynEffector and SysModel classes are abstract base classes so there is no risk of diamond.

The module PDF Description contains further information on this module’s function, how to run it, as well as testing.

Danger

This thruster module is not compatible with variable time step integrators.

Message Connection Descriptions

The following table lists all the module input and output messages. The module msg variable name is set by the user from python. The msg type contains a link to the message structure definition, while the description provides information on what this message is used for.

thrusterDynamicEffector module input and output messages

Module I/O Messages

Msg Variable Name

Msg Type

Description

cmdsInMsg

THRArrayOnTimeCmdMsgPayload

(optional) input message with thruster commands. If not connected the thruster commands are set to zero.

thrusterOutMsgs

THROutputMsgPayload

output message vector for thruster data.

Note

The dynamic behaviour of this module is governed by the variables inside THRTimePair, which determine the on and off-ramp characteristics. The default behaviour is to not have on and off-ramps active. The cutoffFrequency variable inside THRSimConfig has no impact on this module and is instead supposed to be used to determine the dynamic behaviour within C++ Module: thrusterStateEffector.

Initialization and Reset

A linked cmdsInMsg supports at most MAX_EFF_CNT thrusters. Attachment to the hub or a parent state effector, Reset(), and command reading validate this limit and raise BasiliskError before accessing the fixed-size payload. Connecting an input after initialization is checked on the next command read. Larger sets remain supported with the input unlinked; input reading supplies zero commands for all thrusters.

Both attachment paths size the command storage without clearing existing entries. Reset() repeats the count check, zeros the command storage and total mass-flow output, and preserves the individual thrusters’ operating data. Direct calls to ConfigureThrustRequests() may supply partial NewThrustCmds vectors, but the vector cannot exceed the thruster count. Schedule the effector to read commands and publish thruster outputs.

Attaching to a State Effector

This effector supports the branching described in Advanced: Effector Module Branching, so its load can be carried by an appendage instead of the hub. Attach it to the parent state effector rather than to the spacecraft:

stateEff.addDynamicEffector(thrusterSet, segment)

A thruster set built with simIncludeThruster is attached through the factory instead:

thFactory.addToSpacecraftSubcomponent(thrModelTag, thrusterSet, stateEff, segment)

The thrusters then fire from the parent segment’s frame, using its inertial attitude and position in place of the hub’s, so a gimbaled or deployed thruster follows its mount. The segment argument is omitted for a parent with a single degree of freedom.

Both the parent and the child are still added to the task in the usual way, the same as when the child is attached to the hub.

class ThrusterDynamicEffector : public SysModel, public DynamicEffector
#include <thrusterDynamicEffector.h>

thruster dynamic effector class

Public Functions

ThrusterDynamicEffector()

The Constructor.

~ThrusterDynamicEffector()

The destructor.

void linkInStates(DynParamManager &states) override

This method is used to link the states to the thrusters

Parameters:

states – The states to link

void linkInProperties(DynParamManager &properties) override

This method is used to link properties to the thrusters

Parameters:

properties – The parameter manager to collect from

void computeForceTorque(double integTime, double timeStep) override

This method computes the Forces on Torque on the Spacecraft Body.

Parameters:

  • integTime – Integration time

  • timeStep – Current integration time step used

void computeStateContribution(double integTime) override

This method computes contributions to the fuel mass depletion.

Parameters:

integTime – [in] [s] Current integration time.

void Reset(uint64_t CurrentSimNanos) override

This method is used to reset the module.

Parameters:

CurrentSimNanos – [in] [ns] Current simulation time.

void addThruster(std::shared_ptr<THRSimConfig> newThruster)

This method adds new thruster(s) to the thruster set.

Parameters:

newThruster – thruster sim config(s)

void addThruster(std::shared_ptr<THRSimConfig> newThruster, Message<SCStatesMsgPayload> *bodyStateMsg)

This method adds new thruster(s) to the thruster set connected to a different body than the hub.

Parameters:

  • newThruster – thruster sim config(s)

  • bodyStateMsg – body states to which thruster(s) are attached

void UpdateState(uint64_t CurrentSimNanos) override

This method is the main cyclical call for the scheduled part of the thruster dynamics model. It reads the current commands array and sets the thruster configuration data based on that incoming command set. Note that the main dynamical method (ComputeDynamics()) is not called here and is intended to be called from the dynamics plant in the system

Parameters:

CurrentSimNanos – The current simulation time in nanoseconds

void writeOutputMessages(uint64_t CurrentClock)

This method is here to write the output message structure into the specified message.

Parameters:

CurrentClock – The current time used for time-stamping the message

bool ReadInputs()

Read the incoming command message and populate the thruster command vector.

Returns:

Whether a new command is available, or zero commands were supplied for an unlinked input.

void ConfigureThrustRequests(double currentTime)

This method is used to read the new commands vector and set the thruster firings appropriately. It assumes that the ReadInputs method has already been run successfully. It honors all previous thruster firings if they are still active. Note that for unit testing purposes you can insert firings directly into NewThrustCmds.

Parameters:

currentTime – The current simulation time converted to a double

void ComputeThrusterFire(std::shared_ptr<THRSimConfig> CurrentThruster, double currentTime)

This method is used to get the current force for a thruster firing. It uses the configuration data associated with a given thruster and the current clock time to determine what state and force the thruster should be in.

Parameters:

  • CurrentThruster – Pointer to the configuration data for a given thruster

  • currentTime – The current simulation clock time converted to a double

void ComputeThrusterShut(std::shared_ptr<THRSimConfig> CurrentThruster, double currentTime)

This method is used to go through the process of shutting down a thruster once it has been commanded off. It uses the configuration data associated with a given thruster and the current clock time to turn off the thruster according to the ramp profile.

Parameters:

  • CurrentThruster – Pointer to the configuration data for a given thruster

  • currentTime – The current simulation clock time converted to a double

void UpdateThrusterProperties()

This method is used to update the location and orientation of the thrusters at every UpdateState call when the thrusters are attached to a body other than the hub.

void computeBlowDownDecay(std::shared_ptr<THRSimConfig> CurrentThruster)

This method is used to update the blow down effects to the thrust and/or Isp at every computeForceTorque call when the thrusters are attached to a fuel tank subject to blow down effects.

Parameters:

CurrentThruster – [inout] Thruster configuration whose blow-down properties are updated.

double thrFactorToTime(std::shared_ptr<THRSimConfig> thrData, std::vector<THRTimePair> *thrRamp)

This method finds the location in the time in the specified ramp that corresponds to the current thruster thrust factor. It is designed to initialize the ramp-up and ramp-down effects to the appropriate point in their respective ramps based on the initial force

Parameters:

  • thrData – The data for the thruster that we are currently firing

  • thrRamp – This just allows us to avoid switching to figure out which ramp

Returns:

double The time in the ramp associated with the thrust factor

Public Members

ReadFunctor<THRArrayOnTimeCmdMsgPayload> cmdsInMsg

input message with thruster commands

std::vector<Message<THROutputMsgPayload>*> thrusterOutMsgs

output message vector for thruster data

int stepsInRamp

class variable

std::vector<std::shared_ptr<THRSimConfig>> thrusterData

Thruster information.

std::vector<double> NewThrustCmds

Incoming thrust commands.

double mDotTotal

kg/s Current mass flow rate of thrusters

double fuelMass

kg Current total fuel mass of connected fuel tank

double prevFireTime

s Previous thruster firing time

StateData *hubSigma

pointer to the hub attitude states

StateData *hubOmega

pointer to the hub angular velocity states

Eigen::MatrixXd *inertialPositionProperty

[m] r_N inertial position relative to system spice zeroBase/refBase

Eigen::MatrixXd *inertialAttitudeProperty

attitude relative to inertial frame

Eigen::MatrixXd *inertialAngVelocityProperty

[rad/s] inertial angular velocity relative to inertial frame

Eigen::Vector3d r_PcP_P

[m] position vector of parent body CoM w.r.t. parent body frame origin (only used if thrusters attached to non-hub body)

BSKLogger bskLogger

BSK Logging.

Private Functions

void validateConfiguration()

Validate dimensions before accessing thruster data or commands.

Validate configuration dimensions before initialization or command processing.

Private Members

std::vector<THROutputMsgPayload> thrusterOutBuffer

Message buffer for thruster data.

THRArrayOnTimeCmdMsgPayload incomingCmdBuffer

One-time allocation for savings.

std::vector<ReadFunctor<SCStatesMsgPayload>> attachedBodyInMsgs

vector of body states message where the thrusters attach to

SCStatesMsgPayload attachedBodyBuffer
std::vector<BodyToHubInfo> bodyToHubInfo
uint64_t prevCommandTime

Time for previous valid thruster firing.