C++ Module: GravityGradientEffector
Executive Summary
This module, a sub-class of C++ 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.
Msg Variable Name |
Msg Type |
Description |
|---|---|---|
gravityGradientOutMsg |
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
The spacecraft location relative to the \(i^{\text{th}}\) planet is
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 planetName message will contain this
information:
ggEff.addPlanetName(earth.planetName)
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 message is gravityGradientOutMsg.
Initialization and Reset
When the spacecraft links this effector to the hub states and mass properties, initialization verifies that at
least one source planet was supplied with addPlanetName(). This validation occurs even if only the spacecraft
is added to a task.
Force and torque evaluation is driven by the spacecraft dynamics. Add the effector to a task when
gravityGradientOutMsg must be updated, because the effector publishes that message from UpdateState().
When the effector is scheduled, its Reset() repeats the planet-list validation and
zeros all external force and torque outputs. The linked spacecraft and planet property references are retained.
-
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.
- Parameters:
states – [in] Dynamic parameter manager containing the required states and properties.
-
void computeForceTorque(double integTime, double timeStep)
This method computes the body forces and torques for the gravity gradient effector.
- Parameters:
integTime – [in] [s] Current integration time.
timeStep – [in] [s] Integration time step.
-
void Reset(uint64_t CurrentSimNanos)
Reset the effector outputs and validate its configuration.
- Parameters:
CurrentSimNanos – [ns] Time at which the reset occurs
-
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.
- Parameters:
CurrentSimNanos – The current simulation time in nanoseconds
-
void WriteOutputMessages(uint64_t CurrentClock)
Write the gravity gradient torque output message.
- Parameters:
CurrentClock – [in] [ns] Current simulation time.
-
void addPlanetName(std::string planetName)
This method adds planet names to a vector.
- Parameters:
planetName – The planet name
Public Members
-
Message<GravityGradientMsgPayload> gravityGradientOutMsg
output message containing the gravity gradient
-
BSKLogger bskLogger
BSK Logging.
Private Functions
-
void validateConfiguration()
Validate that at least one gravity-gradient source planet was configured.
Private Members
-
std::vector<std::string> planetPropertyNames
Names of planets we want to track.
-
GravityGradientEffector()