Module: GravityGradientEffector¶

Executive Summary¶

This module, a sub-class of Module: dynamicEffector, implements a first order gravity gradient torque acting on a spacecraft. It is written in a general manner such that one or more gravitational objects are considered. This allows a continues simulation to apply gravity gradients torque near the Earth, the moon and onwards to Mars.

Message Connection Descriptions¶

The following table lists all the module input and output messages. The module msg variable name can be 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.

Module I/O Messages¶
Msg Variable Name	Msg Type	Description
gravityGradientOutMsgName	gravityGradientSimMsg	Optional output message name. The default ouput message name is `this->ModelTag + "_gravityGradient"`

Detailed Module Description¶

A first order gravity gradient torque is implemented as discussed in chapter 4 of Analytical Mechanics of Space Systems. Let \([I_c]\) be the total inertia tensor about the spacecraft center of mass location C. Note this \([I_c]\) can vary in time in this effector. Thus, if the spacecraft has a time-varying mass distribution (flexing panels, deploying structures, fuel slosh, etc.), this effector retrieves the current \([I_c]\) value from the dynamics state engine.

Assume a planet center inertial position vector is given by \({\bf R}_{P_i/N}\). If there are N planets contributing to the net gravity gradient torque, then this is evaluated using

(1)¶\[{\bf L}_G = \sum_{i=1}^N \frac{3 \mu}{| {\bf R}_{C/P_i} |^5} {\bf R}_{C/P_i} \times [I_c] {\bf R}_{C/P_i}\]

The spacecraft location relative to the \(i^{\text{th}}\) planet is

(2)¶\[{\bf R}_{C/P_i} = {\bf R}_{C/N} - {\bf R}_{P_i/N}\]

As a spacecraft leaves the sphere of influence of a planet the gravity gradient torque contribution become vanishingly small. This is equivalent to how gravity accelerations are computed relative to all gravitational bodies, regardless of how far away they are. At every time step the gravity gradient effectors is able to pull from the state engine the current planet locations allowing arbitrary integration methods to be used with this external torque.

Module Assumptions and Limitations¶

The effector assumes that a first order gravity gradient torque solution is sufficient to solve the dynamical system.

User Guide¶

Basic Setup¶

The gravity effector setup follows the standard process of creating the effector and asigning it to a spacecraft as well as adding it to the task list:

ggEff = GravityGradientEffector.GravityGradientEffector()
ggEff.ModelTag = scObject.ModelTag
scObject.addDynamicEffector(ggEff)
scSim.AddModelToTask(simTaskName, ggEff)

Specifying Gravity Bodies¶

To specify which planets must be considered for gravity gradient torques, use the command:

ggEff.addPlanetName("name")

where name should be the Spice planetary output name. For example, for earth this is earth_planet_data. If the gravBodyFactory class is used to setup planets, then the bodyInMsgName variable will contain this information:

ggEff.addPlanetName(earth.bodyInMsgName)

Warning

The effector requires at least one planet to be specified.

Note

If you added N gravity bodies for the gravitational acceleration consideration, you don’t have to add all of these objects to the gravity gradient effector as well. It is ok to just add a subset as well. However, any gravity body added to the gravity gradient effector must also have been added as a gravitational body to the spacecraft.

Module Output Message Name¶

The effector write an output message with the current gravity gradient torque information at each update cycle. The output name gravityGradientOutMsgName of this effector can be set using 2 methods.

The default name is auto-created using:

gravityGradientOutMsgName = ``this->ModelTag + "_gravityGradient"``

If the user wishes to use a custom output name, then this can be specified within the python script using:

ggEff.gravityGradientOutMsgName = "custom_gravity_gradient_output_msg_name"

class GravityGradientEffector : public SysModel, public DynamicEffector ¶

#include <GravityGradientEffector.h>

gravity gradient gradient module

Public Functions

GravityGradientEffector()¶

~GravityGradientEffector()¶: The destructor.

void linkInStates(DynParamManager &states)¶

This method is used to link the gravity gradient effector to the hub position, inertia tensor and center of mass vector.

Return: void

void computeForceTorque(double integTime)¶: This method computes the body forces and torques for the gravity gradient effector.

void SelfInit()¶

Create the outgoing gravity gradient torque message.

Return: void

void CrossInit()¶

This method is used to connect to incoming message. For this module there are none.

Return: void

void Reset(uint64_t CurrentSimNanos)¶

This method is used to set the effector, and check same module variables

Return: void

void UpdateState(uint64_t CurrentSimNanos)¶

This method is called once per BSK update cycle. It writes out a msg of the evaluated gravity gradient torque.

Return

void

Parameters

CurrentSimNanos: The current simulation time in nanoseconds

void WriteOutputMessages(uint64_t CurrentClock)¶

Write the gravity gradient torque output message.

Return: void

void addPlanetName(std::string planetName)¶

This method adds planet names to a vector.

Return

void

Parameters

planetName: The planet name

Public Members

std::string gravityGradientOutMsgName¶: message used to read command inputs

StateData *hubSigma¶: Hub/Inertial attitude represented by MRP.

StateData *r_BN_N¶: Hub/Inertial position vector in inertial frame components.

Eigen::MatrixXd *ISCPntB_B¶: [kg m^2] current spacecraft inertia about point B, B-frame components

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

Eigen::MatrixXd *m_SC¶: [kg] mass of spacecraft

std::vector<Eigen::MatrixXd*> r_PN_N¶: [kg] mass of spacecraft

std::vector<Eigen::MatrixXd*> muPlanet¶: [m^3/s^-2] gravitational constant of planet

uint64_t OutputBufferCount¶: number of output buffers for messaging system

BSKLogger bskLogger¶: BSK Logging.

Private Members

int64_t gravityGradientOutMsgId¶: Message ID for outgoing data.

std::vector<std::string> planetPropertyNames¶: Names of planets we want to track.