MuJoCo Warp documentation: inertia matrix automatic sparsity.

PiperOrigin-RevId: 853805011 Change-Id: I8c0040f3b2b08d8615f1fbf559cdc9841e33438a
2026-01-08 10:46:29 -08:00
parent 2f2f9a30ba
commit 166fa17a1c
1 changed files with 15 additions and 0 deletions
@@ -506,6 +506,21 @@ friction values may be sensitive to differences in floating point representation

 If you encounter unexpected results, including NaNs, please open a GitHub issue.

+**Why is inertia matrix qM sparsity not consistent with MuJoCo / MJX?**
+
+.. admonition:: ``mjtJacobian`` semantics
+   :class: note
+
+   - MuJoCo's inertia matrix is always sparse and :ref:`mjtJacobian` affects constraint Jacobians and related quantities
+   - MJWarp's (and MJX's) constraint Jacobian is always dense and :ref:`mjtJacobian` is repurposed to affect the inertia
+     matrix that can be represented as dense or sparse
+
+The automatic sparsity threshold utilized by MJWarp for ``AUTO`` is optimized for GPU and set to ``nv > 32``,
+unlike MuJoCo and MJX which use ``nv >= 60``. Dense ``DENSE`` and sparse ``SPARSE`` settings are consistent with MuJoCo
+and MJX.
+
+This feature is likely to change in the future.
+
 Compilation
 -----------