Add gravity factory support for MuJoCo scenes

docs/source/Support/bskReleaseNotesSnippets/grav-factory-mujoco-scenes.rst

@@ -0,0 +1,3 @@
+- Added ``gravBodyFactory.addBodiesTo()`` support for configuring gravity sources and targets on MuJoCo scenes.
+- Added ``zeroBase`` support to :ref:`planetEphemeris` for expressing all outputs relative to a body propagated by the same module instance.
+- Added :ref:`scenarioMJEarthMoonGravity`, a MuJoCo Earth-Moon gravity tutorial with selectable SPICE or :ref:`planetEphemeris` planet states.

examples/_default.rst

@@ -217,6 +217,7 @@ It's recommended to study the first 6 scenarios in order:
   Chained Hinged Panel Deployment <mujoco/scenarioDeployPanels>
   Solar Radiation Pressure Model on Arbitrary Surfaces <mujoco/scenarioSRPInPanels>
   Landing on Asteroid with Contact Physics <mujoco/scenarioAsteroidLanding>
+  Earth-Moon Gravity with SPICE or PlanetEphemeris <mujoco/scenarioMJEarthMoonGravity>
   Docking between Two CubeSats <mujoco/scenarioSimpleDocking>
   Branching Panel Deployment with Locking Mechanisms <mujoco/scenarioBranchingPanels>
   Pointing with Reaction Wheels in MuJoCo <mujoco/scenarioAttitudeFeedbackRWMuJoCo>

examples/mujoco/scenarioAttitudeFeedbackRWMuJoCo.py

@@ -50,6 +50,11 @@
 #. ``saturationSingleActuator`` optionally clamps each ``SingleActuatorMsg`` to
    emulate actuator torque limits (for example, reaction wheel ``uMax``).
 
+Earth gravity is configured with :ref:`simIncludeGravBody`.  Calling
+``gravFactory.addBodiesTo(scene)`` creates the intermediate
+:ref:`NBodyGravity<NBodyGravity>` model and automatically registers the bus and
+all three reaction wheels as gravity targets.
+
 The simulation runs for 10 minutes. The attitude error, rate error, wheel
 motor torques, and wheel speeds are plotted at the end.
 
@@ -72,10 +77,8 @@
 
 from Basilisk.architecture import messaging
 from Basilisk.fswAlgorithms import attTrackingError, inertial3D, mrpFeedback, rwMotorTorque
-from Basilisk.simulation import NBodyGravity
 from Basilisk.simulation import arrayMotorTorqueToSingleActuators
 from Basilisk.simulation import mujoco
-from Basilisk.simulation import pointMassGravityModel
 from Basilisk.simulation import saturationSingleActuator
 from Basilisk.simulation import scalarJointStatesToRWSpeed
 from Basilisk.simulation import simpleNav
@@ -240,26 +243,16 @@ def run(showPlots: bool = False):
     rwActs = [scene.addJointSingleActuator(f"rw{i+1}Act", rwJoints[i]) for i in range(numRw)]
 
     # -------------------------------------------------------------------------
-    # 5) Add gravity to the special MuJoCo dynamics task (evaluated at integrator substeps)
+    # 5) Add Earth gravity to every MuJoCo body through the gravity factory
     # -------------------------------------------------------------------------
-    gravity = NBodyGravity.NBodyGravity()
-    gravity.ModelTag = "gravity"
-    scene.AddModelToDynamicsTask(gravity)
-
     gravFactory = simIncludeGravBody.gravBodyFactory()
     earth = gravFactory.createEarth()
     earth.isCentralBody = True
-    scene._vizGravBodies = gravFactory.gravBodies
-
     muEarth = earth.mu  # [m^3/s^2]
-    earthPm = pointMassGravityModel.PointMassGravityModel()
-    earthPm.muBody = muEarth
-    gravity.addGravitySource("earth", earthPm, isCentralBody=True)
 
-    # Apply gravity to all bodies to allow consistent orbital motion.
-    gravity.addGravityTarget("bus", busBody)
-    for i in range(numRw):
-        gravity.addGravityTarget(f"rw{i+1}", rwBodies[i])
+    # This creates the NBodyGravity model, adds Earth as its central source, and
+    # registers the bus and all three reaction wheels as gravity targets.
+    gravFactory.addBodiesTo(scene)
 
     # -------------------------------------------------------------------------
     # 6) Navigation: read the bus state from MJScene and publish standard nav outputs

examples/mujoco/scenarioFormationFlyingWithDrag.py

@@ -24,8 +24,9 @@
 as a single point-mass body with three translational sliding joints (x, y, z).
 Their inertial properties are assigned directly in the XML.
 
-Gravity is modeled using the :ref:`NBodyGravity` model, with a point-mass
-Earth defined by :ref:`pointMassGravityModel`. The exponential atmospheric model
+Gravity is configured with :ref:`simIncludeGravBody`.  Its gravity factory
+creates a point-mass Earth and attaches it to the MuJoCo scene, automatically
+applying gravity to both spacecraft.  The exponential atmospheric model
 (:ref:`exponentialAtmosphere`) is optionally added so that the chief and deputy
 can experience cannonball drag.
 
@@ -52,7 +53,7 @@
 
 * How to construct a multi-body MuJoCo scene with two independent spacecraft
 * How to configure translation-only scenarios
-* How to model gravity on multiple bodies using the :ref:`NBodyGravity` model
+* How to configure gravity on multiple MuJoCo bodies using the gravity factory
 * How to apply aerodynamic forces
 * How to configure and apply a classical-element feedback controller for formation control
 * How to record and visualize inertial trajectories, orbital-element histories,
@@ -92,8 +93,6 @@
 from Basilisk.architecture import messaging
 from Basilisk.simulation import mujoco
 from Basilisk.simulation import svIntegrators
-from Basilisk.simulation import pointMassGravityModel
-from Basilisk.simulation import NBodyGravity
 from Basilisk.simulation import cannonballDrag
 from Basilisk.simulation import MJLinearTimeInvariantSystem
 from Basilisk.simulation import exponentialAtmosphere
@@ -161,7 +160,6 @@ class SimulationModels:
     scene: mujoco.MJScene
     chiefBody: mujoco.MJBody
     deputyBody: mujoco.MJBody
-    gravity: NBodyGravity.NBodyGravity
     atmo: exponentialAtmosphere.ExponentialAtmosphere
 
     # Drag models
@@ -321,7 +319,6 @@ def createSimulationModels(
     # Create the MuJoCo scene and add it as a dynamic object
     scene = mujoco.MJScene(CHIEF_DEPUTY_SCENE_XML)
     scene.extraEoMCall = True
-    scene._vizGravBodies = gravFactory.gravBodies
     scSim.AddModelToTask("test", scene, 1)
 
     # Select integrator
@@ -334,16 +331,9 @@ def createSimulationModels(
     chiefBody: mujoco.MJBody = scene.getBody("chief")
     deputyBody: mujoco.MJBody = scene.getBody("deputy")
 
-    # Central body gravity
-    gravity = NBodyGravity.NBodyGravity()
-    gravity.ModelTag = "gravity"
-    scene.AddModelToDynamicsTask(gravity)
-
-    gravityModel = pointMassGravityModel.PointMassGravityModel()
-    gravityModel.muBody = planet.mu
-    gravity.addGravitySource("earth", gravityModel, True)
-    gravity.addGravityTarget("chief", chiefBody)
-    gravity.addGravityTarget("deputy", deputyBody)
+    # The factory creates the NBodyGravity model, adds Earth as its central
+    # source, and registers both spacecraft as gravity targets.
+    gravFactory.addBodiesTo(scene)
 
     # Exponential atmosphere model
     atmo = exponentialAtmosphere.ExponentialAtmosphere()
@@ -360,7 +350,6 @@ def createSimulationModels(
         scene=scene,
         chiefBody=chiefBody,
         deputyBody=deputyBody,
-        gravity=gravity,
         atmo=atmo,
     )