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 connection 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.

Module I/O Messages

Msg Variable Name

Msg Type




gravity gradient output message

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
scSim.AddModelToTask(simTaskName, ggEff)

Specifying Gravity Bodies

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


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:



The effector requires at least one planet to be specified.


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 message is gravityGradientOutMsg.

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

gravity gradient gradient module

Public Functions


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.



void computeForceTorque(double integTime)

This method computes the body forces and torques for the gravity gradient effector.

void Reset(uint64_t CurrentSimNanos)

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



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.


CurrentSimNanos – The current simulation time in nanoseconds



void WriteOutputMessages(uint64_t CurrentClock)

Write the gravity gradient torque output message.



void addPlanetName(std::string planetName)

This method adds planet names to a vector.


planetName – The planet name



Public Members

Message<GravityGradientMsgPayload> gravityGradientOutMsg

output message containing the gravity gradient

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

[m] vector of inertial planet positions

std::vector<Eigen::MatrixXd*> muPlanet

[m^3/s^-2] gravitational constant of planet

BSKLogger bskLogger

BSK Logging.

Private Members

std::vector<std::string> planetPropertyNames

Names of planets we want to track.