Module: spacecraft

Executive Summary

This module provides the spacecraft rigid body translational and rotation motion. It is the typical module used to simulate the 6-DOF spacecraft motion. This spacecraft module is setup such that additional spacecraft effectors can be added such as Module: reactionWheelStateEffector, Module: thrusterDynamicEffector, etc. See Dr. Cody Allard’s dissertation for more information.

This is an instantiation of the Module: dynamicObject abstract class that is a spacecraft with Module: stateEffector’s and Module: dynamicEffector’s attached to it. The spacecraft module allows for both translation and rotation. Module: stateEffector’s such as RWs, flexible solar panel, fuel slosh etc can be added to the spacecraft by attaching stateEffectors. Module: dynamicEffector’s such as thrusters, external force and torque, SRP etc can be added to the spacecraft by attaching dynamicEffectors. This class performs all of this interaction between stateEffectors, dynamicEffectors and the hub.

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

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.

../../../../_images/moduleSpacecraft.svg — Figure 1: `Spacecraft()` Module I/O Illustration

Module I/O Messages
Msg Variable Name	Msg Type	Description
scStateOutMsg	SCStatesMsgPayload	Spacecraft state output message
scMassStateOutMsg	SCMassPropsMsgPayload	Output message containing the spacecraft mass properties
attRefInMsg	AttRefMsgPayload	(Optional) Input message to specify a prescribed attitude motion
transRefInMsg	TransRefMsgPayload	(Optional) Input message to specify a prescribed translational motion

User Guide

This section is to outline the steps needed to setup a Spacecraft module in python using Basilisk.

Import the spacecraft class:

from Basilisk.simulation import spacecraft

Create an instantiation of a spacecraft:
```
scObject = spacecraft.Spacecraft()
```
Define all physical parameters for the hub. For example:
```
scObject.hub.IHubPntBc_B = [[100.0, 0.0, 0.0], [0.0, 50.0, 0.0], [0.0, 0.0, 50.0]]
```
Do this for all of the parameters for a hub:
```
scObject.hub.mHub, scObject.hub.r_BcB_B, scObject.hub.IHubPntBc_B
```
seen in the spacecraft Parameters Table. If you only have translation, you only need to specify the mass (if you only have conservative forces acting on the spacecraft then you don’t even need to specify a mass). If you only have rotation, you only need to specify the inertia, and if you have both, you need to specify the mass, the inertia and if you have a offset between the center of mass of the spacecraft and point \(B\).

Define the initial conditions of the states:

scObject.hub.r_CN_NInit,  scObject.hub.v_CN_NInit, scObject.hub.sigma_BNInit, scObject.hub.omega_BN_BInit

Finally, add the spacecraft to the task:

unitTestSim.AddModelToTask(unitTaskName, scObject)

If you want to prescribe the spacecraft hub rotational motion, this can be specified through an optional input message of type AttRefMsgPayload:
```
scObject.attRefInMsg.subscribeTo(someAttRefMsg)
```
If you want to prescribe the spacecraft hub translational motion, this can be specified through an optional input message of type TransRefMsgPayload:
```
scObject.transRefInMsg.subscribeTo(someTransRefMsg)
```

Spacecraft Parameters Table
Variable Name	Variable Type	Description
r_CN_NInit	double[3]	Inertial position of S/C
v_CN_NInit	double[3]	Inertial velocity of S/C
sigma_BNInit	double[3]	Initial attitude of B frame represented as an MRP
omega_BN_BInit	double[3]	Initial angular velocity of B frame expressed in B frame
mHub	double[1]	Hub mass
IHubPntBc_B	double[3][3]	Inertia in B frame
r_BcB_B	double[3]	Center of mass location in B frame

class Spacecraft : public DynamicObject 

#include <spacecraft.h>

spacecraft dynamic effector

Public Functions

Spacecraft()

Constructor.

This is the constructor, setting variables to default values

~Spacecraft()

Destructor.

This is the destructor, nothing to report here

void initializeDynamics()

This method initializes all of the dynamics and variables for the s/c.

This method is used to initialize the simulation by registering all of the states, linking the dynamicEffectors, stateEffectors, and the hub, initialize gravity, and initialize the sim with the initial conditions specified in python for the simulation

void computeEnergyMomentum(double time)

This method computes the total energy and momentum of the s/c.

This method is used to find the total energy and momentum of the spacecraft. It finds the total orbital energy, total orbital angular momentum, total rotational energy and total rotational angular momentum. These values are used for validation purposes.

void updateSCMassProps(double time)

This method computes the total mass properties of the s/c.

This method is used to update the mass properties of the entire spacecraft using contributions from stateEffectors

void calcForceTorqueFromStateEffectors(double time, Eigen::Vector3d omega_BN_B)

This method computes the force and torque from the stateEffectors.

This method is used to find the force and torque that each stateEffector is applying to the spacecraft. These values are held in the stateEffector class. Additionally, the stateDerivative value is behind the state values because they are calculated in the intergrator calls

void Reset(uint64_t CurrentSimNanos)

This method is used to reset the module.

Returns:: void

void writeOutputStateMessages(uint64_t clockTime)

Method to write all of the class output messages.

This is the method where the messages of the state of vehicle are written

void UpdateState(uint64_t CurrentSimNanos)

Runtime hook back into Basilisk arch.

This method is a part of sysModel and is used to integrate the state and update the state in the messaging system

void linkInStates(DynParamManager &statesIn)

Method to get access to the hub’s states.

This method allows the spacecraft to have access to the current state of the hub for MRP switching, writing messages, and calculating energy and momentum

void equationsOfMotion(double integTimeSeconds, double timeStep)

This method computes the equations of motion for the whole system.

This method is solving Xdot = F(X,t) for the system. The hub needs to calculate its derivatives, along with all of the stateEffectors. The hub also has gravity and dynamicEffectors acting on it and these relationships are controlled in this method. At the end of this method all of the states will have their corresponding state derivatives set in the dynParam Manager thus solving for Xdot

void addStateEffector(StateEffector *newSateEffector)

Attaches a stateEffector to the system.

This method attaches a stateEffector to the dynamicObject

void addDynamicEffector(DynamicEffector *newDynamicEffector)

Attaches a dynamicEffector.

This method attaches a dynamicEffector to the dynamicObject

void preIntegration(double callTime) final

method to perform pre-integration steps

Prepare for integration process

Parameters:: integrateToThisTime – Time to integrate to

void postIntegration(double callTime) final

method to perform post-integration steps

Perform post-integration steps

Parameters:: integrateToThisTime – Time to integrate to

Public Members

uint64_t simTimePrevious: Previous simulation time.

std::string sysTimePropertyName: Name of the system time property.

ReadFunctor<AttRefMsgPayload> attRefInMsg: (optional) reference attitude input message name

ReadFunctor<TransRefMsgPayload> transRefInMsg: (optional) reference translation input message name

double totOrbEnergy: [J] Total orbital kinetic energy

double totRotEnergy: [J] Total rotational energy

double rotEnergyContr: [J] Contribution of stateEffector to total rotational energy

double orbPotentialEnergyContr: [J] Contribution of stateEffector to total rotational energy

double currTimeStep: [s] Time after integration, used for dvAccum calculation

double timePrevious: [s] Time before integration, used for dvAccum calculation

BackSubMatrices backSubContributions: class variable

Eigen::Vector3d sumForceExternal_N: [N] Sum of forces given in the inertial frame

Eigen::Vector3d sumForceExternal_B: [N] Sum of forces given in the body frame

Eigen::Vector3d sumTorquePntB_B: [N-m] Total torque about point B in B frame components

Eigen::Vector3d dvAccum_CN_B: [m/s] Accumulated delta-v of center of mass relative to inertial frame in body frame coordinates

Eigen::Vector3d dvAccum_BN_B: [m/s] accumulated delta-v of body frame relative to inertial frame in body frame coordinates

Eigen::Vector3d dvAccum_CN_N: [m/s] accumulated delta-v of center of mass relative to inertial frame in inertial frame coordinates

Eigen::Vector3d nonConservativeAccelpntB_B: [m/s/s] Current spacecraft body acceleration in the B frame

Eigen::Vector3d omegaDot_BN_B: [rad/s/s] angular acceleration of body wrt to N in body frame

Eigen::Vector3d totOrbAngMomPntN_N: [kg m^2/s] Total orbital angular momentum about N in N frame compenents

Eigen::Vector3d totRotAngMomPntC_N: [kg m^2/s] Total rotational angular momentum about C in N frame compenents

Eigen::Vector3d rotAngMomPntCContr_B: [kg m^2/s] Contribution of stateEffector to total rotational angular mom.

HubEffector hub: The spacecraft plus needs access to the spacecraft hub.

GravityEffector gravField: Gravity effector for gravitational field experienced by spacecraft.

std::vector<StateEffector*> states: Vector of state effectors attached to dynObject.

std::vector<DynamicEffector*> dynEffectors: Vector of dynamic effectors attached to dynObject.

BSKLogger bskLogger: BSK Logging.

Message<SCStatesMsgPayload> scStateOutMsg: spacecraft state output message

Message<SCMassPropsMsgPayload> scMassOutMsg: spacecraft mass properties output message

Private Functions

template<typename Type> inline void assignStateParamNames(Type effector): Assign the state engine state and parameter names to an effector

void readOptionalRefMsg()

Read the optional attitude or translational reference input message and set the reference states.

If the optional attitude reference input message is set, then read in the reference attitude and set it for the hub

Private Members

StateData *hubR_N: State data accesss to inertial position for the hub.

StateData *hubV_N: State data access to inertial velocity for the hub.

StateData *hubOmega_BN_B: State data access to the attitude rate of the hub.

StateData *hubSigma: State data access to sigmaBN for the hub.

StateData *hubGravVelocity: State data access to the gravity-accumulated DV on the Body frame.

StateData *BcGravVelocity: State data access to the gravity-accumulated DV on point Bc.

Eigen::MatrixXd *inertialPositionProperty: [m] r_N inertial position relative to system spice zeroBase/refBase

Eigen::MatrixXd *inertialVelocityProperty: [m] v_N inertial velocity relative to system spice zeroBase/refBase

Eigen::MatrixXd *m_SC: [kg] spacecrafts total mass

Eigen::MatrixXd *mDot_SC: [kg/s] Time derivative of spacecrafts total mass

Eigen::MatrixXd *ISCPntB_B: [kg m^2] Inertia of s/c about point B in B frame components

Eigen::MatrixXd *c_B: [m] Vector from point B to CoM of s/c in B frame components

Eigen::MatrixXd *cPrime_B: [m/s] Body time derivative of c_B

Eigen::MatrixXd *cDot_B: [m/s] Inertial time derivative of c_B

Eigen::MatrixXd *ISCPntBPrime_B: [kg m^2/s] Body time derivative of ISCPntB_B

Eigen::MatrixXd *g_N: [m/s^2] Gravitational acceleration in N frame components

Eigen::MatrixXd *sysTime: [s] System time

Eigen::Vector3d oldOmega_BN_B: [r/s] prior angular rate of B wrt N in the Body frame

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