mujocoDynamics: Runtime body mass updates (mjModel->body_mass/inertia + mj_setConst) trigger MuJoCo instability and NaN acceleration unless model is recompiled

[Blyron]

Describe the bug
When using mujocoDynamics in Basilisk and updating body mass properties at runtime (via the MJBody::massState / updateMujocoModelFromMassProps() path), MuJoCo becomes unstable and Basilisk aborts with Encountered NaN acceleration after ~0.36 s. The issue appears when changing mjModel->body_mass (and optionally inertia) during simulation and then calling mj_setConst (and even mj_forward) to refresh derived constants. In contrast, recompiling the model after mass changes avoids the instability.

Typical symptoms include MuJoCo warnings at time 0.0000 such as:

MuJoCo internal warning: Nan, Inf or huge value in CTRL at ACTUATOR ...

MuJoCo internal warning: Inertia matrix is too close to singular at DOF ...

Then Basilisk terminates with:

_bskLogging.BasiliskError: Encountered NaN acceleration at time 0.366667s in MJScene with ID: ...

To reproduce
Steps to reproduce the behavior:
Use Basilisk mujocoDynamics/_GeneralModuleFiles with an MJCF model containing multiple bodies, including joints/actuators (e.g., thrusters and reaction wheels).

Create an MJScene and run a simulation with MJScene::equationsOfMotion() calling:

updateMujocoArraysFromStates()

MJBody::updateMujocoModelFromMassProps() for bodies whose mass varies

mj_setConst(m, d) (and mj_forward(m, d)) when constants are marked stale

Drive mass changes at runtime using a Basilisk message subscribed to derivativeMassPropertiesInMsg (e.g., SCMassPropsMsgPayload.massSC nonzero, such as -1.0).

Run the simulation for a few frames (≈ 11 steps at ~30 Hz).

Observe MuJoCo internal warnings at Time = 0.0000 and then Basilisk aborting around t ≈ 0.366667 s with NaN acceleration.

Example reproduction (high level):

Add a module or code path that updates MJBody::massState during runtime (e.g., fuel consumption) and calls MJBody::updateMujocoModelFromMassProps().

Simulate with a multi-body satellite model including wheel joints/actuators.

Observe: Inertia matrix is too close to singular ... and later Encountered NaN acceleration ....

Expected behavior
Updating mass properties at runtime (mass-only, or mass + inertia) should be stable when followed by the documented update calls (mj_setConst, potentially mj_forward / kinematics refresh), without requiring a full MuJoCo recompile. In other words, changing mjModel->body_mass (and mjModel->body_inertia if required) should not lead to NaN accelerations if the update pipeline is correct.
Screenshots
If applicable, add screenshots/plots to help explain your problem.

BSK_WARNING: MuJoCo internal warning: Inertia matrix is too close to singular at DOF X. Check model. Time = 0.0000.

BSK_WARNING: MuJoCo internal warning: Nan, Inf or huge value in CTRL at ACTUATOR Y. The simulation is unstable. Time = 0.0000.

_bskLogging.BasiliskError: Encountered NaN acceleration at time 0.366667s in MJScene with ID: ...

Desktop (please complete the following information):
Desktop (please complete the following information):

OS: Linux (Docker container / Ubuntu-based environment)

Version: (Ubuntu 22)

Python version: 3.11 (venv)

Additional context
The instability only occurs when runtime mass change is enabled (e.g., SCMassPropsMsgPayload.massSC != 0.0). If massSC = 0.0, the simulation runs without triggering this NaN acceleration failure.

Recompiling the MuJoCo model after mass changes prevents the NaN failure, but recompilation is too expensive for complex models and is not viable for per-step mass updates.

We tried multiple implementations of MJBody::updateMujocoModelFromMassProps():

mass-only updates (more stable but not physically consistent)

mass + inertia scaling (more correct but tends to reintroduce instability unless recompiling)

calling mj_setConst and mj_forward immediately after marking constants stale

The model includes “encapsulation” bodies intended to be semantically massless (0 mass) and some roots that intentionally have small mass (e.g., 0.1 kg).

Potential solution directions:

Provide a supported runtime-safe pathway in Basilisk mujocoDynamics for changing mass/inertia without requiring mj_recompile, possibly by applying updates at the mjSpec level or by forcing a more complete internal refresh that remains performant.

Add defensive handling in Basilisk for massless/near-massless bodies and near-singular DOFs (e.g., automatic stabilization or warnings) when runtime mass updates are enabled.

Clarify/document which MuJoCo “constant” fields can be changed safely at runtime and what exact sequence of MuJoCo calls is required (beyond mj_setConst) for stability in articulated models.