Add mju_sym2dense, document future breakage of mj_fullM

PiperOrigin-RevId: 910242375
Change-Id: Ibfbdef9cfb66088723499ea257da09aee0d80938

doc/APIreference/functions.rst

@@ -3982,6 +3982,15 @@ Convert matrix from dense to sparse.
 
 Convert matrix from sparse to dense.
 
+.. _mju_sym2dense:
+
+`mju_sym2dense <#mju_sym2dense>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mju_sym2dense
+
+Convert lower-triangular symmetric CSR matrix to full dense matrix.
+
 .. _Quaternions:
 
 Quaternions

doc/changelog.rst

@@ -5,6 +5,8 @@ Changelog
 Upcoming version (not yet released)
 -----------------------------------
 
+General
+^^^^^^^
 - Added island support for the :ref:`PGS solver<soAlgorithms>`.
 - Added support for :ref:`elastic2d<body-flexcomp-elastic2d>` for trilinear and quadratic flex
   :ref:`dofs<body-flexcomp-dof>`.
@@ -13,6 +15,18 @@ Upcoming version (not yet released)
   (nonzero :ref:`density<option-density>` or :ref:`viscosity<option-viscosity>`).
   Midpoint integration treats external forces as zero-order-hold constants, which causes
   energy gain in the presence of contacts and in fluid media.
+- Added :ref:`mju_sym2dense`, converting a lower-triangular, implicitly symmetric CSR matrix to a dense
+  symmetric matrix. The inertia matrix ``mjData.M`` is an example of such a matrix.
+
+.. admonition:: Future breaking API changes
+   :class: warning
+
+   - The introduction of :ref:`mju_sym2dense` is a step towards the removal of the legacy-format ``mjData.qM`` in favor
+     of the CSR-format ``mjData.M``. This removal will involve a future breaking change to :ref:`mj_fullM` (which
+     currently accepts a ``qM``-like matrix as an argument). To prevent a future breakage, replace
+     ``mj_fullM(m, dst, d->qM)``  with
+     |br| ``mju_sym2dense(dst, d->M, m->nv, m->M_rownnz, m->M_rowadr, m->M_colind)``.
+
 
 Python
 ^^^^^^

doc/includes/references.h

@@ -3522,6 +3522,8 @@ int mju_dense2sparse(mjtNum* res, const mjtNum* mat, int nr, int nc,
                      int* rownnz, int* rowadr, int* colind, int nnz);
 void mju_sparse2dense(mjtNum* res, const mjtNum* mat, int nr, int nc,
                       const int* rownnz, const int* rowadr, const int* colind);
+void mju_sym2dense(mjtNum* res, const mjtNum* mat, int n,
+                   const int* rownnz, const int* rowadr, const int* colind);
 void mju_rotVecQuat(mjtNum res[3], const mjtNum vec[3], const mjtNum quat[4]);
 void mju_negQuat(mjtNum res[4], const mjtNum quat[4]);
 void mju_mulQuat(mjtNum res[4], const mjtNum quat1[4], const mjtNum quat2[4]);