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 back-substitution 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 back-substitution 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)
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

&#8212; 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)

&#8212; Setter for the tank frame orientation

set fuel tank orientation relative to the hub frame

Eigen::Matrix3d getDcm_TB() const

&#8212; 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

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)

&#8212; Setter for update only mass depletion

set update only mass depletion flag

bool getUpdateOnly() const

&#8212; 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

double getFuelLeakRate() const

[kg/s] Getter for the fuel leak rate

get fuel leak rate

void pushFuelSloshParticle(FuelSlosh *particle)

&#8212; Attach fuel slosh particle

Attach a fuel slosh particle to the tank

void registerStates(DynParamManager &states) override

&#8212; Register mass state with state manager

Register states. The fuel tank has one state associated with it: mass, and it also has the responsibility to call register states for the fuel slosh particles

void linkInStates(DynParamManager &states) override

&#8212; Give the tank access to other states

Link states that the module accesses

void updateEffectorMassProps(double integTime) override

&#8212; Add contribution mass props from the tank

Fuel tank add its contributions the mass of the vehicle.

void setNameOfMassState(const std::string &nameOfMassState)

&#8212; Setter for fuel tank mass state name

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

std::string getNameOfMassState() const

&#8212; Getter for fuel tank mass state name

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

void addThrusterSet(ThrusterDynamicEffector *dynEff)

&#8212; Add DynamicEffector thruster

Attach a thruster dynamic effector to the tank

void addThrusterSet(ThrusterStateEffector *stateEff)

&#8212; Add StateEffector thruster

Attach a thruster state effector to the tank

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

&#8212; Back-sub contributions

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

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

&#8212; Energy and momentum calculations

Fuel tank contributes to the energy and momentum calculations

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

&#8212; Calculate stateEffector’s derivatives

Fuel tank computes its derivative

Public Members

std::vector<FuelSlosh*> fuelSloshParticles

&#8212; vector of fuel slosh particles

std::vector<ThrusterDynamicEffector*> thrDynEffectors

&#8212; Vector of dynamic effectors for thrusters

std::vector<ThrusterStateEffector*> thrStateEffectors

&#8212; Vector of state effectors for thrusters

ReadFunctor<MassFlowRateMsgPayload> fuelLeakRateInMsg

(optional) fuel leak mass flow rate input message

Message<FuelTankMsgPayload> fuelTankOutMsg = {}

&#8212; fuel tank output message name

FuelTankMsgPayload fuelTankMassPropMsg = {}

instance of messaging system message struct

std::string nameOfMassState = {}

&#8212; Legacy public mass state name; Python users should use accessors

Eigen::Matrix3d dcm_TB

&#8212; 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

&#8212; Legacy public update-only flag; Python users should use accessors

double fuelLeakRate = {}

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

Private Members

StateData *omegaState = {}

&#8212; state data for omega_BN of the hub

StateData *massState = {}

&#8212; 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

&#8212; style of tank to simulate

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

&#8212; 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