C++ Module: fuelTank

Executive Summary

This class is an instantiation of the stateEffector abstract class and implements an effector representing a fuel tank. This fuel tank has one state associated with it and is the mass of the fuel inside the tank. The module is a fuel tank effector attached to a rigid body hub and has the following functions:

  • Compute tank properties depending on the tank model being used

  • Provides its contributions to the mass properties of the spacecraft

  • Provides its contributions to the Backsubstitution matrices

  • Computes its derivative for its mass flow rate using the vector of attached thrusters

  • Provides its contributions to energy and momentum of the spacecraft

The module PDF Description contains further information on this module’s computations.

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.

fuelTank module input and output messages

Module I/O Messages

Msg Variable Name

Msg Type

Description

fuelTankOutMsg

FuelTankMsgPayload

fuel tank output message name

fuelLeakRateInMsg

MassFlowRateMsgPayload

optional fuel leak mass flow rate input message that overrides setFuelLeakRate()

User Guide

The fuel tank effector module must be passed a tank model

fuelTankEffector = fuelTank.FuelTank()
tankModel = fuelTank.FuelTankModelConstantVolume()
fuelTankEffector.setTankModel(tankModel)

Fuel tank configuration values should be set and read with the module setter and getter methods. Direct Python access to the legacy public variables nameOfMassState, dcm_TB, r_TB_B, updateOnly, and fuelLeakRate is deprecated and raises a deprecation warning.

The configurable values are:

  • setNameOfMassState() / getNameOfMassState(): optional state name used when registering the fuel tank mass state. Set this before simulation initialization if a custom state name is required.

  • setDcm_TB() / getDcm_TB(): direction cosine matrix from the body frame B to the tank frame T.

  • setR_TB_B() / getR_TB_B(): position vector from the body-frame origin to the tank point, expressed in body-frame components in meters.

  • setUpdateOnly() / getUpdateOnly(): flag selecting update-only mass depletion. The default value is True. Set this to False to include the additional mass-depletion Backsubstitution contributions.

  • setFuelLeakRate() / getFuelLeakRate(): positive fuel mass flow rate leaving the tank in kg/s. This leak rate is added to any attached thruster fuel consumption and reduces the reported fuel mass without applying force or torque to the spacecraft. The leak stops when the available tank propellant reaches zero, and the module logs a BSK_WARNING the first time depletion reaches an empty tank.

The leak rate can also be supplied through the optional fuelLeakRateInMsg input message. If this message is connected, the message massFlowRate value overrides the value configured with setFuelLeakRate().

fuelTankEffector.setNameOfMassState("fuelTankMass1")
fuelTankEffector.setDcm_TB([[1.0, 0.0, 0.0],
                            [0.0, 1.0, 0.0],
                            [0.0, 0.0, 1.0]])
fuelTankEffector.setR_TB_B([[0.0], [0.0], [0.1]])  # [m]
fuelTankEffector.setUpdateOnly(True)
fuelTankEffector.setFuelLeakRate(1.0e-5)  # [kg/s]

fuelLeakRateMsgData = messaging.MassFlowRateMsgPayload()
fuelLeakRateMsgData.massFlowRate = 2.0e-5  # [kg/s]
fuelLeakRateMsg = messaging.MassFlowRateMsg().write(fuelLeakRateMsgData)
fuelTankEffector.fuelLeakRateInMsg.subscribeTo(fuelLeakRateMsg)

A thruster effector can be attached to a tank effector to simulate fuel mass depletion by thruster operation.

fuelTankEffector.addThrusterSet(thrustersEffector)

When attaching fuel-slosh particles, add the tank to C++ Module: spacecraft before the particles. During each integration stage, the tank reads the current particle masses and allocates the total propellant outflow; the particles then report their allocated component rates during the same mass-property assembly.

fuelTankEffector.pushFuelSloshParticle(sloshParticle)
spacecraftObject.addStateEffector(fuelTankEffector)
spacecraftObject.addStateEffector(sloshParticle)
class FuelTankModel
#include <fuelTank.h>

Tank model class

Subclassed by FuelTankModelCentrifugalBurn, FuelTankModelConstantDensity, FuelTankModelConstantVolume, FuelTankModelEmptying, FuelTankModelUniformBurn

Public Functions

virtual void computeTankProps(double mFuel) = 0

class method

virtual void computeTankPropDerivs(double mFuel, double mDotFuel) = 0

class method

inline FuelTankModel()
virtual ~FuelTankModel() = default

Public Members

double propMassInit = {}

[kg] Initial propellant mass in tank

double maxFuelMass = 1.0

[kg] maximum tank mass

Eigen::Vector3d r_TcT_TInit

[m] Initial position vector from B to tank point in B frame comp.

Eigen::Matrix3d ITankPntT_T

[kg m^2] Inertia of tank about pnt T in B frame comp.

Eigen::Matrix3d IPrimeTankPntT_T

[kg m^2/s] Derivative of inertia of tank about pnt T in B frame comp.

Eigen::Vector3d r_TcT_T

[m] position vector from B to tank point in B frame comp.

Eigen::Vector3d rPrime_TcT_T

[m/s] Derivative of position vector from B to tank point in B frame comp.

Eigen::Vector3d rPPrime_TcT_T

[m/s^2] Second derivative of position vector from B to tank point in B frame comp.

class FuelTankModelConstantVolume : public FuelTankModel
#include <fuelTank.h>

Tank constant volume class

Public Functions

FuelTankModelConstantVolume() = default
~FuelTankModelConstantVolume() override = default
inline virtual void computeTankProps(double mFuel) override

class method

inline virtual void computeTankPropDerivs(double mFuel, double mDotFuel) override

class method

Public Members

double radiusTankInit = {}

[m] Initial radius of the spherical tank

class FuelTankModelConstantDensity : public FuelTankModel
#include <fuelTank.h>

Tank constant density class

Public Functions

FuelTankModelConstantDensity() = default
~FuelTankModelConstantDensity() override = default
inline virtual void computeTankProps(double mFuel) override

class method

inline virtual void computeTankPropDerivs(double mFuel, double mDotFuel) override

class method

Public Members

double radiusTankInit = {}

[m] Initial radius of the spherical tank

double radiusTank = {}

[m] Current radius of the spherical tank

class FuelTankModelEmptying : public FuelTankModel
#include <fuelTank.h>

Tank model emptying class

Public Functions

FuelTankModelEmptying() = default
~FuelTankModelEmptying() override = default
inline virtual void computeTankProps(double mFuel) override

class method

inline virtual void computeTankPropDerivs(double mFuel, double mDotFuel) override

class method

Public Members

double radiusTankInit = {}

[m] Initial radius of the spherical tank

double rhoFuel = {}

[kg/m^3] density of the fuel

double thetaStar = {}

[rad] angle from vertical to top of fuel

double thetaDotStar = {}

[rad/s] derivative of angle from vertical to top of fuel

double thetaDDotStar = {}

[rad/s^2] second derivative of angle from vertical to top of fuel

Eigen::Vector3d k3

Direction of fuel depletion.

class FuelTankModelUniformBurn : public FuelTankModel
#include <fuelTank.h>

Tank model class for a uniform burn

Public Functions

FuelTankModelUniformBurn() = default
~FuelTankModelUniformBurn() override = default
inline virtual void computeTankProps(double mFuel) override

class method

inline virtual void computeTankPropDerivs(double mFuel, double mDotFuel) override

class method

Public Members

double radiusTankInit = {}

[m] Initial radius of the cylindrical tank

double lengthTank = {}

[m] Length of the tank

class FuelTankModelCentrifugalBurn : public FuelTankModel
#include <fuelTank.h>

Tank model class for a centrifugal burn

Public Functions

FuelTankModelCentrifugalBurn() = default
~FuelTankModelCentrifugalBurn() override = default
inline virtual void computeTankProps(double mFuel) override

class method

inline virtual void computeTankPropDerivs(double mFuel, double mDotFuel) override

class method

Public Members

double radiusTankInit = {}

[m] Initial radius of the cylindrical tank

double lengthTank = {}

[m] Length of the tank

double radiusInner = {}

[m] Inner radius of the cylindrical tank

class FuelTank : public StateEffector, public SysModel
#include <fuelTank.h>

Fuel tank effector model class

Public Functions

FuelTank()
~FuelTank()
void writeOutputMessages(uint64_t currentClock)

Compute fuel tank mass properties and outputs them as a message.

Parameters:

currentClock – The current simulation time (used for time stamping)

void UpdateState(uint64_t currentSimNanos) override

Fuel tank writes out its messages

Parameters:

currentSimNanos – The current simulation time in nanoseconds

void setTankModel(std::shared_ptr<FuelTankModel> model)

set fuel tank model

Parameters:

model – fuel tank model type

void setDcm_TB(const Eigen::Matrix3d &dcm_TB)

Setter for the tank frame orientation.

set fuel tank orientation relative to the hub frame

Parameters:

dcm_TB – [in] Direction cosine matrix defining the tank orientation relative to the hub.

Eigen::Matrix3d getDcm_TB() const

Getter for the tank frame orientation.

get fuel tank orientation relative to the hub frame

void setR_TB_B(const Eigen::Vector3d &r_TB_B)

[m] Setter for the tank location

set fuel tank location relative to the hub frame

Parameters:

r_TB_B – [in] [m] Tank position relative to the hub, expressed in body-frame components.

Eigen::Vector3d getR_TB_B() const

[m] Getter for the tank location

get fuel tank location relative to the hub frame

void setUpdateOnly(bool updateOnly)

Setter for update only mass depletion.

set update only mass depletion flag

Parameters:

updateOnly – [in] Flag selecting update-only mass depletion.

bool getUpdateOnly() const

Getter for update only mass depletion.

get update only mass depletion flag

void setFuelLeakRate(double fuelLeakRate)

[kg/s] Setter for the fuel leak rate

set fuel leak rate

Parameters:

fuelLeakRate – [in] [kg/s] Fuel leak mass flow rate.

double getFuelLeakRate() const

[kg/s] Getter for the fuel leak rate

get fuel leak rate

void pushFuelSloshParticle(FuelSlosh *particle)

Attach fuel slosh particle.

Attach a fuel slosh particle to the tank

Parameters:

particle – [in] Fuel-slosh particle to attach.

void registerStates(DynParamManager &states) override

Register mass state with state manager.

Register the tank mass state before any attached fuel-slosh states.

Parameters:

states – [inout] Dynamic parameter manager used to register the tank mass state.

void linkInStates(DynParamManager &states) override

Give the tank access to other states.

Link states that the module accesses

Parameters:

states – [in] Dynamic parameter manager containing the required states.

void updateEffectorMassProps(double integTime) override

Add contribution mass props from the tank.

Fuel tank adds its contribution to the mass of the vehicle.

Parameters:

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

void setNameOfMassState(const std::string &nameOfMassState)

Setter for fuel tank mass state name.

optionally set the name of the mass state to be used by the state manager

Parameters:

nameOfMassState – [in] Name assigned to the tank mass state.

std::string getNameOfMassState() const

Getter for fuel tank mass state name.

get the name of the mass state used by the state manager

void addThrusterSet(ThrusterDynamicEffector *dynEff)

Add DynamicEffector thruster.

Attach a thruster dynamic effector to the tank

Parameters:

dynEff – [in] Thruster dynamic effector to attach.

void addThrusterSet(ThrusterStateEffector *stateEff)

Add StateEffector thruster.

Attach a thruster state effector to the tank

Parameters:

stateEff – [in] Thruster state effector to attach.

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

Back-sub contributions.

Fuel tank adds its contributions to the matrices for the back-sub method.

Parameters:

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

  • backSubContr – [inout] Backsubstitution contributions.

  • sigma_BN – [in] Hub attitude relative to the inertial frame.

  • omega_BN_B – [in] [rad/s] Hub angular velocity expressed in body-frame components.

  • g_N – [in] [m/s^2] Gravitational acceleration expressed in inertial-frame components.

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

Energy and momentum calculations.

Fuel tank contributes to the energy and momentum calculations

Parameters:

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

  • rotAngMomPntCContr_B – [inout] [kg*m^2/s] Rotational angular momentum contribution.

  • rotEnergyContr – [inout] [J] Rotational energy contribution.

  • omega_BN_B – [in] [rad/s] Hub angular velocity expressed in body-frame components.

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

Calculate stateEffector’s derivatives.

Fuel tank computes its derivative

Parameters:

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

  • rDDot_BN_N – [in] [m/s^2] Hub translational acceleration expressed in inertial-frame components.

  • omegaDot_BN_B – [in] [rad/s^2] Hub angular acceleration expressed in body-frame components.

  • sigma_BN – [in] Hub attitude relative to the inertial frame.

Public Members

std::vector<FuelSlosh*> fuelSloshParticles

vector of fuel slosh particles

std::vector<ThrusterDynamicEffector*> thrDynEffectors

Vector of dynamic effectors for thrusters.

std::vector<ThrusterStateEffector*> thrStateEffectors

Vector of state effectors for thrusters.

ReadFunctor<MassFlowRateMsgPayload> fuelLeakRateInMsg

(optional) fuel leak mass flow rate input message

Message<FuelTankMsgPayload> fuelTankOutMsg = {}

fuel tank output message name

FuelTankMsgPayload fuelTankMassPropMsg = {}

instance of messaging system message struct

std::string nameOfMassState = {}

Legacy public mass state name; Python users should use accessors.

Eigen::Matrix3d dcm_TB

Legacy public DCM from body frame to tank frame.

Eigen::Vector3d r_TB_B

[m] Legacy public tank position in B frame; Python users should use accessors

bool updateOnly = true

Legacy public update-only flag; Python users should use accessors.

double fuelLeakRate = {}

[kg/s] Legacy public leak rate; Python users should use accessors

Private Functions

void updateRetainedMassPropertyDerivatives(double mass, double massRate)

Update derivatives of the retained tank mass properties.

Parameters:

  • mass – [in] [kg] Mass value.

  • massRate – [in] [kg/s] Mass rate.

Private Members

StateData *omegaState = {}

state data for omega_BN of the hub

StateData *massState = {}

state data for mass state

double fuelConsumption = {}

[kg/s] rate of fuel being consumed

double tankFuelConsumption = {}

[kg/s] rate of fuel being consumed from tank

std::shared_ptr<FuelTankModel> fuelTankModel

style of tank to simulate

Eigen::Matrix3d ITankPntT_B
Eigen::Vector3d r_TcB_B
bool emptyTankWarningPrinted = false

flag indicating if the empty tank warning has been logged

Private Static Attributes

static uint64_t effectorID = 1

[] ID number of this fuel tank effector