Add boolean flags for gravity compensation and surface velocity in mjModel.

These fields (`flg_gravcomp` and `flg_surfacevel`) replace the fast-path checks originally guarded by `ngravcomp` and (recently) `nsurfacevel`. Since the engine uses these integers only as flags (zero vs non-zero), migrating them to actual booleans makes them writeable from the Python bindings at runtime without violating size/dimension constraints.

The legacy integer field `ngravcomp` is marked as deprecated and will be removed in a future release.

PiperOrigin-RevId: 949779204
Change-Id: Ifab1f026063a4239302e6ad689663b611b59dda8

doc/changelog.rst

@@ -72,7 +72,12 @@ General
   integrator and flex stiffness present; Newton and PGS are unaffected. Bending-only models pay zero per-step
   factorization cost (the factor is precomputed in :ref:`mj_setConst<mj_setConst>`). Inverse dynamics
   (:ref:`mj_inverse<mj_inverse>`) is now discrete-consistent with forward dynamics for gated models.
-- The ``mjz`` decoder now searches for ``model.xml`` at the root of the archive as a fallback if the archive-named XML is not found.
+- The ``mjz`` decoder now searches for ``model.xml`` at the root of the archive as a fallback if the archive-named XML
+  is not found.
+- Added ``flg_gravcomp`` and ``flg_surfacevel`` boolean flags to ``mjModel``. These flags replace the fast-path checks
+  as originally guarded by ``ngravcomp``. Since the engine uses these integers as flags (zero vs. non-zero), the new
+  flags are honest boolean properties, writeable from the Python bindings at runtime. The field ``ngravcomp`` is
+  deprecated and will be removed in a future release.
 
 .. admonition:: Breaking API changes
    :class: attention

doc/includes/references.h

@@ -661,7 +661,6 @@ typedef struct mjModel_ {
   mjtSize nnames_map;             // number of slots in the names hash map
   mjtSize nJmom;                  // number of non-zeros in sparse actuator_moment matrix
   mjtSize ngravcomp;              // number of bodies with nonzero gravcomp
-  mjtSize nsurfacevel;            // number of geoms with nonzero surfacevel
   mjtSize nemax;                  // number of potential equality-constraint rows
   mjtSize njmax;                  // number of available rows in constraint Jacobian (legacy)
   mjtSize nconmax;                // number of potential contacts in contact list (legacy)
@@ -676,6 +675,11 @@ typedef struct mjModel_ {
   mjtSize narena;                 // number of bytes in the mjData arena (inclusive of stack)
   mjtSize nbuffer;                // number of bytes in buffer
 
+  // ------------------------------- flags
+
+  mjtBool flg_gravcomp;           // whether any body has nonzero gravcomp
+  mjtBool flg_surfacevel;         // whether any geom has nonzero surfacevel
+
   // ------------------------------- options and statistics
 
   mjOption opt;                   // physics options

doc/programming/simulation.rst

@@ -715,8 +715,9 @@ Exceptions to the general rule that **real-valued** types **are safe to change**
      - Unsafe for static bodies, invalidates the midphase collision structures (BVH).
    * - ``body_gravcomp``
      - Safe.
-     - If the number of bodies with gravity compensation is changed from zero to non-zero,
-       :ref:`mj_setConst` must be called.
+     - If passing from a state where all bodies have zero gravity compensation to a state where some bodies have
+       non-zero gravity compensation (or vice-versa), the ``flg_gravcomp`` flag in :ref:`mjModel` must be updated.
+       This can be done directly or by calling :ref:`mj_setConst`.
    * - ``dof_armature``
      - Safe with :ref:`mj_setConst`.
      -
@@ -725,8 +726,9 @@ Exceptions to the general rule that **real-valued** types **are safe to change**
      -
    * - ``geom_surfacevel``
      - Safe.
-     - If the number of geoms with nonzero surface velocity is changed from zero to non-zero (or vice versa),
-       :ref:`mj_setConst` must be called.
+     - If passing from a state where all geoms have zero surface velocity to a state where some geoms have
+       non-zero surface velocity (or vice-versa), the ``flg_surfacevel`` flag in :ref:`mjModel` must be updated.
+       This can be done directly or by calling :ref:`mj_setConst`.
    * - ``{site,cam,light}_`` |br| ``{pos,quat}``
      - Mostly safe.
      - For cameras and lights with tracking or targeting, :ref:`mj_setConst` is required.