C++ Module: NBodyGravity

Executive Summary

The NBodyGravity module computes gravitational forces on one or more targets due to one or more gravity sources and applies those forces in a MuJoCo simulation. It supports arbitrary gravity models and can be tied to MuJoCo sites or bodies for direct force application.

Message Interfaces

Messages are registered per source and per target via addGravitySource and addGravityTarget.

Module I/O Messages
Msg Variable Name	Msg Type	Description
source.stateInMsg	SpicePlanetStateMsgPayload	Inertial position and velocity of the gravity source (e.g., from SPICE). One per registered source.
target.massPropertiesInMsg	SCMassPropsMsgPayload	Mass properties of the gravity target. One per registered target.
target.centerOfMassStateInMsg	SCStatesMsgPayload	Inertial state (position, velocity, attitude) of the target’s center of mass. One per registered target.
target.massFixedForceOutMsg	ForceAtSiteMsgPayload	Output gravitational force expressed in the site frame. One per registered target.

Module Description

For each gravity target, the module accumulates the gravitational acceleration from all sources:

\[\mathbf{a} = \sum_k \mathbf{a}_k(\mathbf{r})\]

where \(\mathbf{a}_k\) is the acceleration from source \(k\) evaluated at the target’s position \(\mathbf{r}\) in the inertial frame. The resulting force is

\[\mathbf{F} = m\,\mathbf{a}\]

and is published as a ForceAtSiteMsgPayload in the site frame.

If one source is designated as the central body, the central-body acceleration is subtracted from all other targets (third-body perturbation formulation).

Multiple gravity sources and targets can be registered. Each source provides its own GravityModel (e.g., point-mass or spherical harmonics) and its inertial state via stateInMsg. Each target provides mass properties and center-of-mass state via massPropertiesInMsg and centerOfMassStateInMsg.

Detailed Behavior

At each update step, the module performs the following operations for each target:

Reads the target mass and center-of-mass state.
For each gravity source, reads its inertial state and evaluates the gravity model.
Sums accelerations from all sources (applying the third-body formulation if a central body is defined).
Multiplies by target mass to obtain force.
Writes the result to target.massFixedForceOutMsg.

During Reset(), the module validates that all source and target input messages are linked and that at most one central body is defined.

Module Assumptions and Limitations

The module computes forces at the target center of mass; torques due to gravity gradient are not modeled.
Sources and targets are processed in insertion order (alphabetical by name in the internal map).

Verification and Testing

The module is verified in src/simulation/mujocoDynamics/NBodyGravity/_UnitTest/test_gravity.py.

struct GravitySource

#include <NBodyGravity.h>

Represents a gravity source in an N-body simulation.

A gravity source is a celestial body or point mass that generates a gravitational field.

Public Members

std::shared_ptr<GravityModel> model: The gravity model associated with the source.

ReadFunctor<SpicePlanetStateMsgPayload> stateInMsg: Input message providing the state of the source.

bool isCentralBody: Flag indicating whether this source is the central body.

struct GravityTarget

#include <NBodyGravity.h>

Represents a gravity target in an N-body simulation.

A gravity target is a body or site subject to gravitational forces.

Public Members

ReadFunctor<SCMassPropsMsgPayload> massPropertiesInMsg: Input message for the target’s mass properties.

ReadFunctor<SCStatesMsgPayload> centerOfMassStateInMsg: Input message for the target’s state.

Message<ForceAtSiteMsgPayload> massFixedForceOutMsg: Output message for the computed force.

class NBodyGravity : public SysModel 

#include <NBodyGravity.h>

Simulates N-body gravitational interactions.

The NBodyGravity class manages gravitational forces between multiple sources and targets, computing the resultant forces on the targets due to the gravitational fields of the sources.

Public Functions

void Reset(uint64_t CurrentSimNanos)

Resets the N-body gravity simulation.

Ensures all sources and targets input messages are linked, that at most one central source is defined, and initializes the source gravity model parameters.

Parameters:: CurrentSimNanos – The current simulation time in nanoseconds.
Throws:: std::runtime_error – If there are configuration errors.

void UpdateState(uint64_t CurrentSimNanos)

Updates the gravitational force of all targets.

Parameters:: CurrentSimNanos – The current simulation time in nanoseconds.

GravitySource &addGravitySource(std::string name, std::shared_ptr<GravityModel> gravityModel, bool isCentralBody)

Adds a new gravity source to the simulation.

A gravity source is a celestial body or point mass that generates a gravitational field.

Remember to link the stateInMsg of the returned source.

Parameters:

name – The name of the gravity source.
gravityModel – The gravity model associated with the source.
isCentralBody – Indicates if this is the central body (only one per simulation).

Throws:

std::invalid_argument – If the source name is duplicated.

Returns:

A reference to the newly added GravitySource.

GravityTarget &addGravityTarget(std::string name)

Adds a new gravity target to the simulation.

A gravity target is a body or site subject to gravitational forces.

Remember to link the massPropertiesInMsg and centerOfMassStateInMsg messages of the returned target.

Parameters:: name – The name of the gravity target.
Throws:: std::invalid_argument – If the target name is duplicated.
Returns:: A reference to the newly added GravityTarget.

GravityTarget &addGravityTarget(std::string name, MJSite &site)

Adds a gravity target tied to a specific site.

The gravity field is computed at the site’s position/orientation, and the gravity force/torque is applied at a newly created actuator on this site.

Remember to tie the massPropertiesInMsg message of the returned target.

Parameters:

name – The name of the gravity target.
site – The site associated with the target.

Returns:

A reference to the newly added GravityTarget.

GravityTarget &addGravityTarget(std::string name, MJBody &body)

Adds a gravity target tied to a specific body.

The gravity field is computed at the body’s center mass, and the gravity force/torque is applied at a newly created actuator on this site.

Parameters:

name – The name of the gravity target.
body – The body associated with the target.

Returns:

A reference to the newly added GravityTarget.

inline GravitySource &getGravitySource(std::string name)

Retrieves a gravity source by name.

Parameters:: name – The name of the gravity source.
Throws:: std::out_of_range – If the source does not exist.
Returns:: A reference to the GravitySource.

inline GravityTarget &getGravityTarget(std::string name)

Retrieves a gravity target by name.

Parameters:: name – The name of the gravity target.
Throws:: std::out_of_range – If the target does not exist.
Returns:: A reference to the GravityTarget.

Eigen::Vector3d computeAccelerationFromSource(GravitySource &source, Eigen::Vector3d r_J2000)

Computes the gravitational acceleration from a source at a position.

Parameters:

source – The gravity source.
r_J2000 – The position vector in the J2000 frame.

Returns:

The gravitational acceleration vector.

Eigen::Vector3d computeAccelerationOnTarget(GravityTarget &target)

Computes the total gravitational acceleration acting on a target.

Parameters:: target – The gravity target.
Returns:: The gravitational acceleration vector.

Public Members

BSKLogger bskLogger: BSK Logging.

Protected Attributes

std::map<std::string, GravitySource> sources: Map of gravity sources by name.

std::map<std::string, GravityTarget> targets: Map of gravity targets by name.