Add gravity factory support for MuJoCo scenes by schaubh · Pull Request #1490 · AVSLab/basilisk

schaubh · 2026-07-20T20:57:58Z

Review: By commit
Merge strategy: Merge (no squash)

Description

This PR extends simIncludeGravBody.gravBodyFactory so the same gravity-body configuration can be attached to conventional Basilisk spacecraft dynamics or a MuJoCo MJScene.

MuJoCo users can now configure gravity with the standard factory workflow:

gravFactory = simIncludeGravBody.gravBodyFactory()
earth = gravFactory.createEarth()
earth.isCentralBody = True
gravFactory.addBodiesTo(scene)

For a MuJoCo scene, addBodiesTo() creates and retains an NBodyGravity model, adds the factory bodies as gravity sources, and registers every MuJoCo body as a gravity target at its center of mass. The gravity-body configuration is also exposed to Vizard. Duplicate attachment to a scene is rejected.

NBodyGravity now accepts shared GravBodyData descriptors. This preserves each body’s gravity model, central-body designation, and ephemeris input without duplicating configuration between conventional and MuJoCo dynamics. The existing manual NBodyGravity APIs remain available.

This PR also adds PlanetEphemeris.zeroBase. When set to a body propagated by the module, all output positions and velocities are translated relative to that body while retaining J2000-aligned axes. Leaving zeroBase empty preserves the existing heliocentric behavior. Body-name matching is case-insensitive, and invalid selections stop initialization with an error.

A new scenarioMJEarthMoonGravity tutorial demonstrates Earth and Moon gravity using either SPICE or PlanetEphemeris. It includes correct ephemeris scheduling, safe low-Earth-orbit initial conditions, Vizard binary-saving support, and illustrative plots.

Existing MuJoCo examples and appropriate MuJoCo-backed tests were migrated to the factory helper. Tests that intentionally exercise the low-level NBodyGravity configuration APIs remain explicit.

The commits are organized as follows:

Add GravBodyData and MuJoCo-scene support to NBodyGravity and gravBodyFactory.
Improve the gravity factory comments and user guidance.
Add and document PlanetEphemeris.zeroBase.
Add the Earth-Moon MuJoCo gravity tutorial.
Migrate existing MuJoCo examples to the gravity factory.
Migrate appropriate MuJoCo-backed unit tests.
Add release-note snippets.

Verification

The following validation was performed:

Rebuilt the planetEphemeris C++ and SWIG target.
Ran all 18 PlanetEphemeris unit tests.
Ran all 14 MuJoCo example scenario tests.
Ran all 67 tests under src/simulation/mujocoDynamics.
Ran all 6 cannonball-drag tests.
Ran the updated custom-gravity-body scenario test.
Ran the Earth-Moon tutorial with both SPICE and PlanetEphemeris.
Verified that the spacecraft remains safely above the Earth’s atmosphere.
Verified both ephemeris configurations in Vizard.
Ran the applicable pre-commit hooks.
Ran Python compilation and diff whitespace checks.

No test baselines were re-generated or relaxed.

Documentation

The following documentation was added or updated:

Expanded the simIncludeGravBody module documentation and inline comments.
Documented PlanetEphemeris.zeroBase, including default behavior, usage, and limitations.
Added the required warning that zeroBase only works with bodies propagated by the same PlanetEphemeris instance.
Added scenarioMJEarthMoonGravity and linked it from the example index.
Documented the SPICE and analytical ephemeris configuration paths and their scheduling requirements.
Updated existing MuJoCo examples to use and describe the gravity-factory workflow.
Updated scenarioCustomGravBody to use an asteroid-centered ephemeris origin.
Added release-note snippets for the factory support, zeroBase, and tutorial.

Reviewers should pay particular attention to the GravBodyData ownership and ephemeris connections in NBodyGravity, the automatic MuJoCo target registration in gravBodyFactory.addBodiesTo(), and the two-pass state translation in PlanetEphemeris.

Future work

No required follow-up is currently identified.

Cross-instance PlanetEphemeris.zeroBase support remains intentionally out of scope because separate module instances do not exchange propagated body states.

Extend gravBodyFactory.addBodiesTo() to configure MJScene objects in addition to conventional GravityEffector owners. For each MuJoCo scene, create an NBodyGravity model, register every factory body as a gravity source, and apply gravity independently at every MuJoCo body's center of mass. Retain the model and Vizard gravity metadata on the scene and reject duplicate gravity attachment. Allow NBodyGravity sources to retain a shared GravBodyData descriptor. Resolve the gravity model, central-body flag, and ephemeris input from the descriptor so the same configuration can be shared by conventional spacecraft and MuJoCo dynamics. Initialize descriptor-backed gravity models during Reset and warn when an orientation-dependent model has no ephemeris input. Expose descriptor-backed sources to Python as addGravitySourceFromBody(). Keep the existing manual addGravitySource(..., isCentralBody=...) interface unchanged, including support for its keyword argument. This enables gravity models and SPICE connections created by simIncludeGravBody to be reused directly by MuJoCo scenes without duplicating their configuration.

…novice user

Add an optional zeroBase setting to PlanetEphemeris so generated planet states can be expressed relative to another body propagated by the same module instance. Preserve the existing heliocentric behavior when zeroBase is left empty. Resolve the selected body during Reset using case-insensitive name matching and report an initialization error when the requested body is not configured in the module. Compute all heliocentric states before subtracting the selected body's position and velocity, ensuring the translation is independent of body ordering. Leave planet names, timestamps, attitudes, attitude rates, and orientation flags unchanged. Expand the PlanetEphemeris unit tests to verify: - the default empty zeroBase value - position and velocity translation at multiple simulation times - zero position and velocity for the selected base body - preservation of attitude and message metadata - case-insensitive body-name matching - rejection of bodies from outside the module instance Document zeroBase configuration, default behavior, and the requirement that the reference body be propagated by the same PlanetEphemeris instance. Clarify that changing the output origin does not introduce hierarchical or mutually coupled orbital propagation. Update scenarioCustomGravBody to use Itokawa as the output origin, placing the planet and spacecraft states in a common asteroid-centered translational frame.

Example uses both Spice and planetEphemeris message states.

…propriate

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2bbbd8c1fb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Add an optional zeroBase setting to PlanetEphemeris so generated planet states can be expressed relative to another body propagated by the same module instance. Preserve the existing heliocentric behavior when zeroBase is left empty. Resolve the selected body during Reset using case-insensitive name matching and report an initialization error when the requested body is not configured in the module. Compute all heliocentric states before subtracting the selected body's position and velocity, ensuring the translation is independent of body ordering. Leave planet names, timestamps, attitudes, attitude rates, and orientation flags unchanged. Expand the PlanetEphemeris unit tests to verify: - the default empty zeroBase value - position and velocity translation at multiple simulation times - zero position and velocity for the selected base body - preservation of attitude and message metadata - case-insensitive body-name matching - rejection of bodies from outside the module instance Document zeroBase configuration, default behavior, and the requirement that the reference body be propagated by the same PlanetEphemeris instance. Clarify that changing the output origin does not introduce hierarchical or mutually coupled orbital propagation. Update scenarioCustomGravBody to use Itokawa as the output origin, placing the planet and spacecraft states in a common asteroid-centered translational frame.

Example uses both Spice and planetEphemeris message states.

…propriate

Treat an all-zero J20002Pfix matrix from a linked gravity-source ephemeris message as an identity transformation. Position-only ephemeris messages leave J20002Pfix at its default zero value. Applying that matrix previously collapsed transformed target positions to zero, which could produce a singular gravity calculation and NaN forces. The new fallback matches the existing GravityEffector behavior and interprets an unspecified source attitude as inertially aligned. Add a MuJoCo regression test using a factory-created central gravity body connected to a position-only ephemeris message. Verify that the computed force remains finite and agrees with the analytical point-mass gravity result. Verification: - NBodyGravity unit tests: 11 passed - MuJoCo dynamics tests: 68 passed - pre-commit checks passed - git diff --check passed

juan-g-bonilla

Focused mostly on the NBodyGravity changes and usage. Left two nitpick-y comments and suggested a fix for what I think gets you stale recorded data. Otherwise the scenarios look much nicer with the factory!

Extend gravBodyFactory.addBodiesTo() to configure MJScene objects in addition to conventional GravityEffector owners. For each MuJoCo scene, create an NBodyGravity model, register every factory body as a gravity source, and apply gravity independently at every MuJoCo body's center of mass. Retain the model and Vizard gravity metadata on the scene and reject duplicate gravity attachment. Allow NBodyGravity sources to retain a shared GravBodyData descriptor. Resolve the gravity model, central-body flag, and ephemeris input from the descriptor so the same configuration can be shared by conventional spacecraft and MuJoCo dynamics. Initialize descriptor-backed gravity models during Reset and warn when an orientation-dependent model has no ephemeris input. Expose descriptor-backed sources to Python as addGravitySourceFromBody(). Keep the existing manual addGravitySource(..., isCentralBody=...) interface unchanged, including support for its keyword argument. This enables gravity models and SPICE connections created by simIncludeGravBody to be reused directly by MuJoCo scenes without duplicating their configuration.

…novice user

Add an optional zeroBase setting to PlanetEphemeris so generated planet states can be expressed relative to another body propagated by the same module instance. Preserve the existing heliocentric behavior when zeroBase is left empty. Resolve the selected body during Reset using case-insensitive name matching and report an initialization error when the requested body is not configured in the module. Compute all heliocentric states before subtracting the selected body's position and velocity, ensuring the translation is independent of body ordering. Leave planet names, timestamps, attitudes, attitude rates, and orientation flags unchanged. Expand the PlanetEphemeris unit tests to verify: - the default empty zeroBase value - position and velocity translation at multiple simulation times - zero position and velocity for the selected base body - preservation of attitude and message metadata - case-insensitive body-name matching - rejection of bodies from outside the module instance Document zeroBase configuration, default behavior, and the requirement that the reference body be propagated by the same PlanetEphemeris instance. Clarify that changing the output origin does not introduce hierarchical or mutually coupled orbital propagation. Update scenarioCustomGravBody to use Itokawa as the output origin, placing the planet and spacecraft states in a common asteroid-centered translational frame.

Example uses both Spice and planetEphemeris message states.

…propriate

Treat an all-zero J20002Pfix matrix from a linked gravity-source ephemeris message as an identity transformation. Position-only ephemeris messages leave J20002Pfix at its default zero value. Applying that matrix previously collapsed transformed target positions to zero, which could produce a singular gravity calculation and NaN forces. The new fallback matches the existing GravityEffector behavior and interprets an unspecified source attitude as inertially aligned. Add a MuJoCo regression test using a factory-created central gravity body connected to a position-only ephemeris message. Verify that the computed force remains finite and agrees with the analytical point-mass gravity result. Verification: - NBodyGravity unit tests: 11 passed - MuJoCo dynamics tests: 68 passed - pre-commit checks passed - git diff --check passed

Extend gravBodyFactory.addBodiesTo() to configure MJScene objects in addition to conventional GravityEffector owners. For each MuJoCo scene, create an NBodyGravity model, register every factory body as a gravity source, and apply gravity independently at every MuJoCo body's center of mass. Retain the model and Vizard gravity metadata on the scene and reject duplicate gravity attachment. Allow NBodyGravity sources to retain a shared GravBodyData descriptor. Resolve the gravity model, central-body flag, and ephemeris input from the descriptor so the same configuration can be shared by conventional spacecraft and MuJoCo dynamics. Initialize descriptor-backed gravity models during Reset and warn when an orientation-dependent model has no ephemeris input. Expose descriptor-backed sources to Python as addGravitySourceFromBody(). Keep the existing manual addGravitySource(..., isCentralBody=...) interface unchanged, including support for its keyword argument. This enables gravity models and SPICE connections created by simIncludeGravBody to be reused directly by MuJoCo scenes without duplicating their configuration.

…novice user

Add an optional zeroBase setting to PlanetEphemeris so generated planet states can be expressed relative to another body propagated by the same module instance. Preserve the existing heliocentric behavior when zeroBase is left empty. Resolve the selected body during Reset using case-insensitive name matching and report an initialization error when the requested body is not configured in the module. Compute all heliocentric states before subtracting the selected body's position and velocity, ensuring the translation is independent of body ordering. Leave planet names, timestamps, attitudes, attitude rates, and orientation flags unchanged. Expand the PlanetEphemeris unit tests to verify: - the default empty zeroBase value - position and velocity translation at multiple simulation times - zero position and velocity for the selected base body - preservation of attitude and message metadata - case-insensitive body-name matching - rejection of bodies from outside the module instance Document zeroBase configuration, default behavior, and the requirement that the reference body be propagated by the same PlanetEphemeris instance. Clarify that changing the output origin does not introduce hierarchical or mutually coupled orbital propagation. Update scenarioCustomGravBody to use Itokawa as the output origin, placing the planet and spacecraft states in a common asteroid-centered translational frame.

Example uses both Spice and planetEphemeris message states.

…propriate

schaubh requested a review from juan-g-bonilla July 20, 2026 20:57

schaubh self-assigned this Jul 20, 2026

schaubh requested a review from a team as a code owner July 20, 2026 20:57

schaubh added documentation Improvements or additions to documentation enhancement New feature or request labels Jul 20, 2026

schaubh added this to Basilisk Jul 20, 2026

schaubh added a commit that referenced this pull request Jul 20, 2026

[#1490] update the grav factory comments to be more descriptive to a …

5169b64

…novice user

schaubh force-pushed the feature/grav_factory_mujoco branch from 2bbbd8c to b0a9b37 Compare July 20, 2026 21:01

schaubh added a commit that referenced this pull request Jul 20, 2026

[#1490] add new mujoco example showing how to add gravity bodies

7c07c06

Example uses both Spice and planetEphemeris message states.

schaubh added a commit that referenced this pull request Jul 20, 2026

[#1490] update existing mujoco examples to use gravity factor class

900fba4

schaubh added a commit that referenced this pull request Jul 20, 2026

[#1490] updated mujoco unit tests to use gravity factor class when ap…

f8d8a53

…propriate

schaubh added a commit that referenced this pull request Jul 20, 2026

[#1490] add release note snippets

b0a9b37

chatgpt-codex-connector Bot reviewed Jul 20, 2026

View reviewed changes

Comment thread examples/scenarioCustomGravBody.py Outdated

Comment thread src/simulation/mujocoDynamics/NBodyGravity/NBodyGravity.cpp

schaubh added a commit that referenced this pull request Jul 20, 2026

[#1490] add new mujoco example showing how to add gravity bodies

24958c9

Example uses both Spice and planetEphemeris message states.

schaubh added a commit that referenced this pull request Jul 20, 2026

[#1490] update existing mujoco examples to use gravity factor class

fa16c2d

schaubh added a commit that referenced this pull request Jul 20, 2026

[#1490] updated mujoco unit tests to use gravity factor class when ap…

83ef502

…propriate

schaubh force-pushed the feature/grav_factory_mujoco branch from b0a9b37 to f209d89 Compare July 20, 2026 23:59

schaubh added a commit that referenced this pull request Jul 20, 2026

[#1490] add release note snippets

f69a307

juan-g-bonilla approved these changes Jul 22, 2026

View reviewed changes

Comment thread src/simulation/mujocoDynamics/NBodyGravity/NBodyGravity.cpp Outdated

Comment thread src/utilities/simIncludeGravBody.py Outdated

Comment thread examples/mujoco/scenarioMJEarthMoonGravity.py Outdated

schaubh added 7 commits July 21, 2026 19:23

[#1490] update the grav factory comments to be more descriptive to a …

fd83626

…novice user

[#1490] add new mujoco example showing how to add gravity bodies

7942a97

Example uses both Spice and planetEphemeris message states.

[#1490] update existing mujoco examples to use gravity factor class

6b1e6ff

[#1490] updated mujoco unit tests to use gravity factor class when ap…

451b61b

…propriate

[#1490] add release note snippets

3047326

schaubh force-pushed the feature/grav_factory_mujoco branch from f209d89 to c0fd86a Compare July 22, 2026 01:23

schaubh merged commit 8eb951c into develop Jul 22, 2026
7 checks passed

schaubh added a commit that referenced this pull request Jul 22, 2026

[#1490] update the grav factory comments to be more descriptive to a …

617fe97

…novice user

schaubh added a commit that referenced this pull request Jul 22, 2026

[#1490] add new mujoco example showing how to add gravity bodies

64aa418

Example uses both Spice and planetEphemeris message states.

schaubh added a commit that referenced this pull request Jul 22, 2026

[#1490] update existing mujoco examples to use gravity factor class

d4b205e

schaubh deleted the feature/grav_factory_mujoco branch July 22, 2026 02:31

schaubh added a commit that referenced this pull request Jul 22, 2026

[#1490] updated mujoco unit tests to use gravity factor class when ap…

ca25ec0

…propriate

schaubh added a commit that referenced this pull request Jul 22, 2026

[#1490] add release note snippets

a91559a

github-project-automation Bot moved this to ✅ Done in Basilisk Jul 22, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add gravity factory support for MuJoCo scenes#1490

Add gravity factory support for MuJoCo scenes#1490
schaubh merged 8 commits into
developfrom
feature/grav_factory_mujoco

schaubh commented Jul 20, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

Uh oh!

juan-g-bonilla left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

schaubh commented Jul 20, 2026

Description

Verification

Documentation

Future work

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

juan-g-bonilla left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants