Module: gravityEffector

Executive Summary

Abstract class that is used to implement an effector impacting a GRAVITY body that does not itself maintain a state or represent a changing component of the body (for example: gravity, thrusters, solar radiation pressure, etc.)

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




central planet body state output message

The gravity effector contains a list of GravBodyData objects which contain the planet mass and size properties etc. The following table lists the Spice planet ephemeris input message that can be connected to a GravBodyData object. If no message is connected, then the planet has zero position and orientation information by default.

Module I/O Messages

Msg Variable Name

Msg Type




planet spice ephemerisis input message

User Guide

The user must provide a list of GravBodyData objects to the spacecraft using:

scObject.gravField.gravBodies = spacecraft.GravBodyVector(gravBodyList)

Each gravity body data object can be created using:

earth = gravityEffector.GravBodyData()
earth.planetName = 'earth_planet_data' = 0.3986004415E+15  # meters^3/s^2
earth.radEquator = 6378136.6  # meters
earth.isCentralBody = False

Note that the helper file contains a gravity body factor class to facilitate setting up gravity bodies.

class GravBodyData
#include <gravityEffector.h>

Container for gravitational body data

This class is designed to hold all of the information for a gravity body. The nominal use-case has it initialized at the python level and attached to dynamics using the AddGravityBody method.

Public Functions


Initializes localPlanet to zero except for localPlanet.J20002Pfix, which is initialized to the identity matrix. Additionally, initializes gravityModel to a PointMassGravityModel.

void initBody(int64_t moduleID)

Initializes the gravityModel, logging and raising an error if the initialization fails.

Eigen::Vector3d computeGravityInertial(Eigen::Vector3d r_I, uint64_t simTimeNanos)

Computes the gravitational acceleration

  • r_I – inertial position vector

  • simTimeNanos – simulation time (ns)

void loadEphemeris()

Read the ephemeris data from planetBodyInMsg if it’s linked. Otherwise, zeros this->localPlanet.

void registerProperties(DynParamManager &statesIn)

Creates the following properies in the given statesIn object.

- [planetName].r_PN_N
- [planetName].v_PN_N
- [planetName].mu
- [planetName].J20002Pfix
- [planetName].J20002Pfix_dot
vr_PN_N,v_PN_N, andmuare initialized to zero, whileJ20002PfixandJ20002Pfix_dot are initialized to the values stored inthis->localPlanet. This usually means that J20002Pfixis initialized to the identity matrix andJ20002Pfix_dot` to zero.

Public Members

bool isCentralBody = false

Flag indicating that object is center

std::shared_ptr<GravityModel> gravityModel

Model used to compute the gravity of the object

double mu = 0

[m3/s^2] central body gravitational param

double radEquator = 0

[m] Equatorial radius for the body

double radiusRatio = 1

[] ratio of polar over equatorial radius

std::string planetName = ""

Gravitational body name, this is used as the Spice name if spiceInterface is used

std::string displayName = ""

This is the name that is displayed in Vizard. If not set, Vizard shows planetName

std::string modelDictionaryKey = ""

“” will result in using the current default for the celestial body’s given name, otherwise key will be matched if possible to available model in internal model dictionary

ReadFunctor<SpicePlanetStateMsgPayload> planetBodyInMsg

planet spice ephemeris input message

SpicePlanetStateMsgPayload localPlanet

[-] Class storage of ephemeris info from scheduled portion

BSKLogger bskLogger

&#8212; BSK Logging

Private Members

Eigen::MatrixXd *r_PN_N

[m] (state engine property) planet inertial position vector

Eigen::MatrixXd *v_PN_N

[m/s] (state engine property) planet inertial velocity vector

Eigen::MatrixXd *muPlanet

[m/s] (state engine property) planet inertial velocity vector

Eigen::MatrixXd *J20002Pfix

[m/s] (state engine property) planet attitude [PN]

Eigen::MatrixXd *J20002Pfix_dot

[m/s] (state engine property) planet attitude rate [PN_dot]

uint64_t timeWritten = 0

[ns] time the input planet state message was written


friend class GravityEffector
class GravityEffector : public SysModel
#include <gravityEffector.h>

gravity effector class

Public Functions

void Reset(uint64_t currentSimNanos)

Initializes every GravBodyData associated with this GravityEffector

void UpdateState(uint64_t currentSimNanos)

Updates the central body, loads the ephemeris data for every GravBodyData, and writes the output messages.

void linkInStates(DynParamManager &statesIn)

Links the correlation between times property

void registerProperties(DynParamManager &statesIn)

Registers the gravity, inertial position, and inertial velocity properties. It also calls registerProperties for every associated GravBodyData.

void computeGravityField(Eigen::Vector3d r_cF_N, Eigen::Vector3d rDot_cF_N)

Calculate gravitational acceleration of s/c wrt inertial (no central body) or wrt central body

  • r_cF_N – is position of center of mass of s/c wrt frame

  • rDot_cF_N – is the derivative of above

void updateInertialPosAndVel(Eigen::Vector3d r_BF_N, Eigen::Vector3d rDot_BF_N)

Updates the inertial position and velocity properties

void updateEnergyContributions(Eigen::Vector3d r_CN_N, double &orbPotEnergyContr)

Computes the Potential Energy Contributions from every associated GravBodyData

void setGravBodies(std::vector<std::shared_ptr<GravBodyData>> gravBodies)

Sets the GravBodyData associated with this effector

void addGravBody(std::shared_ptr<GravBodyData> gravBody)

Adds a GravBodyData associated with this effector

void prependSpacecraftNameToStates()

Called to modify property names to prepend them by the string stored in nameOfSpacecraftAttachedTo

This can be used to make property names unique between different GravityEffector in a simulation with multiple dynamic objects.

Public Members

std::vector<std::shared_ptr<GravBodyData>> gravBodies

[-] Vector of bodies we feel gravity from

std::shared_ptr<GravBodyData> centralBody

Central body

std::string vehicleGravityPropName = "g_N"

[-] Name of the vehicle gravity acceleration property

std::string systemTimeCorrPropName = "systemTime"

[-] Name of the correlation between times

std::string inertialPositionPropName = "r_BN_N"

[-] Name of the inertial position property

std::string inertialVelocityPropName = "v_BN_N"

[-] Name of the inertial velocity property

std::string nameOfSpacecraftAttachedTo = ""

[-] Name of the s/c this gravity model is attached to

Message<SpicePlanetStateMsgPayload> centralBodyOutMsg

central planet body state output message

BSKLogger bskLogger

&#8212; BSK Logging

Private Functions

Eigen::Vector3d getEulerSteppedGravBodyPosition(std::shared_ptr<GravBodyData> bodyData)

Compute planet position with Euler integration


bodyData – planet data

void writeOutputMessages(uint64_t currentSimNanos)

Writes to centralBodyOutMsg if it is linked and there is a central body

Private Members

Eigen::MatrixXd *gravProperty

[-] g_N property for output

Eigen::MatrixXd *timeCorr

[-] Time correlation property

Eigen::MatrixXd *inertialPositionProperty

[m] r_N inertial position relative to system spice zeroBase/refBase coordinate frame, property for output.

Eigen::MatrixXd *inertialVelocityProperty

[m/s] v_N inertial velocity relative to system spice zeroBase/refBase coordinate frame, property for output.