Rename spec to sig in state-related API functions.

(to avoid confusion with mjSpec)

PiperOrigin-RevId: 795848898
Change-Id: I0b64eb85f5c7a3ee889a746c751d9f5561650277

doc/APIreference/functions.rst

@@ -235,7 +235,7 @@ computations, and are documented in more detail below.
 
 .. mujoco-include:: mj_stateSize
 
-Returns the number of :ref:`mjtNum` |-| s required for a given state specification. The bits of the integer ``spec``
+Returns the number of :ref:`mjtNum` |-| s required for a given state signature. The bits of the integer ``sig``
 correspond to element fields of :ref:`mjtState`.
 
 .. _mj_getState:
@@ -245,8 +245,8 @@ correspond to element fields of :ref:`mjtState`.
 
 .. mujoco-include:: mj_getState
 
-Copy concatenated state components specified by ``spec`` from ``d`` into ``state``. The bits of the integer
+Copy concatenated state components specified by ``sig`` from ``d`` into ``state``. The bits of the integer
-``spec`` correspond to element fields of :ref:`mjtState`. Fails with :ref:`mju_error` if ``spec`` is invalid.
+``sig`` correspond to element fields of :ref:`mjtState`. Fails with :ref:`mju_error` if ``sig`` is invalid.
 
 .. _mj_setState:
 
@@ -255,8 +255,8 @@ Copy concatenated state components specified by ``spec`` from ``d`` into ``state
 
 .. mujoco-include:: mj_setState
 
-Copy concatenated state components specified by ``spec`` from  ``state`` into ``d``. The bits of the integer
+Copy concatenated state components specified by ``sig`` from  ``state`` into ``d``. The bits of the integer
-``spec`` correspond to element fields of :ref:`mjtState`. Fails with :ref:`mju_error` if ``spec`` is invalid.
+``sig`` correspond to element fields of :ref:`mjtState`. Fails with :ref:`mju_error` if ``sig`` is invalid.
 
 .. _mj_setKeyframe:
 

doc/APIreference/functions_override.rst

@@ -181,18 +181,18 @@ computations, and are documented in more detail below.
 
 .. _mj_stateSize:
 
-Returns the number of :ref:`mjtNum` |-| s required for a given state specification. The bits of the integer ``spec``
+Returns the number of :ref:`mjtNum` |-| s required for a given state signature. The bits of the integer ``sig``
 correspond to element fields of :ref:`mjtState`.
 
 .. _mj_getState:
 
-Copy concatenated state components specified by ``spec`` from ``d`` into ``state``. The bits of the integer
+Copy concatenated state components specified by ``sig`` from ``d`` into ``state``. The bits of the integer
-``spec`` correspond to element fields of :ref:`mjtState`. Fails with :ref:`mju_error` if ``spec`` is invalid.
+``sig`` correspond to element fields of :ref:`mjtState`. Fails with :ref:`mju_error` if ``sig`` is invalid.
 
 .. _mj_setState:
 
-Copy concatenated state components specified by ``spec`` from  ``state`` into ``d``. The bits of the integer
+Copy concatenated state components specified by ``sig`` from  ``state`` into ``d``. The bits of the integer
-``spec`` correspond to element fields of :ref:`mjtState`. Fails with :ref:`mju_error` if ``spec`` is invalid.
+``sig`` correspond to element fields of :ref:`mjtState`. Fails with :ref:`mju_error` if ``sig`` is invalid.
 
 .. _mj_mulJacVec:
 

doc/includes/references.h

@@ -3105,9 +3105,9 @@ void mj_projectConstraint(const mjModel* m, mjData* d);
 void mj_referenceConstraint(const mjModel* m, mjData* d);
 void mj_constraintUpdate(const mjModel* m, mjData* d, const mjtNum* jar,
                          mjtNum cost[1], int flg_coneHessian);
-int mj_stateSize(const mjModel* m, unsigned int spec);
+int mj_stateSize(const mjModel* m, unsigned int sig);
-void mj_getState(const mjModel* m, const mjData* d, mjtNum* state, unsigned int spec);
+void mj_getState(const mjModel* m, const mjData* d, mjtNum* state, unsigned int sig);
-void mj_setState(const mjModel* m, mjData* d, const mjtNum* state, unsigned int spec);
+void mj_setState(const mjModel* m, mjData* d, const mjtNum* state, unsigned int sig);
 void mj_setKeyframe(mjModel* m, const mjData* d, int k);
 int mj_addContact(const mjModel* m, mjData* d, const mjContact* con);
 int mj_isPyramidal(const mjModel* m);

include/mujoco/mujoco.h

@@ -430,14 +430,14 @@ MJAPI void mj_constraintUpdate(const mjModel* m, mjData* d, const mjtNum* jar,
 
 //---------------------------------- Support -------------------------------------------------------
 
-// Return size of state specification.
+// Return size of state signature.
-MJAPI int mj_stateSize(const mjModel* m, unsigned int spec);
+MJAPI int mj_stateSize(const mjModel* m, unsigned int sig);
 
 // Get state.
-MJAPI void mj_getState(const mjModel* m, const mjData* d, mjtNum* state, unsigned int spec);
+MJAPI void mj_getState(const mjModel* m, const mjData* d, mjtNum* state, unsigned int sig);
 
 // Set state.
-MJAPI void mj_setState(const mjModel* m, mjData* d, const mjtNum* state, unsigned int spec);
+MJAPI void mj_setState(const mjModel* m, mjData* d, const mjtNum* state, unsigned int sig);
 
 // Copy current state to the k-th model keyframe.
 MJAPI void mj_setKeyframe(mjModel* m, const mjData* d, int k);

python/mujoco/bindings_test.py

@@ -768,36 +768,36 @@ class MuJoCoBindingsTest(parameterized.TestCase):
   def test_getsetstate(self):  # pylint: disable=invalid-name
     mujoco.mj_step(self.model, self.data)
 
-    # Test for invalid state spec
+    # Test for invalid state signature
-    invalid_spec = 2**mujoco.mjtState.mjNSTATE.value
+    invalid_sig = 2**mujoco.mjtState.mjNSTATE.value
     expected_message = (
-        f'mj_stateSize: invalid state spec {invalid_spec} >= 2^mjNSTATE'
+        f'mj_stateSize: invalid state signature {invalid_sig} >= 2^mjNSTATE'
     )
     with self.assertRaisesWithLiteralMatch(mujoco.FatalError, expected_message):
-      mujoco.mj_stateSize(self.model, invalid_spec)
+      mujoco.mj_stateSize(self.model, invalid_sig)
 
-    spec = mujoco.mjtState.mjSTATE_INTEGRATION
+    sig = mujoco.mjtState.mjSTATE_INTEGRATION
-    size = mujoco.mj_stateSize(self.model, spec)
+    size = mujoco.mj_stateSize(self.model, sig)
 
     state_bad_size = np.empty(size + 1, np.float64)
-    expected_message = 'state size should equal mj_stateSize(m, spec)'
+    expected_message = 'state size should equal mj_stateSize(m, sig)'
     with self.assertRaisesWithLiteralMatch(TypeError, expected_message):
-      mujoco.mj_getState(self.model, self.data, state_bad_size, spec)
+      mujoco.mj_getState(self.model, self.data, state_bad_size, sig)
 
     # Get initial state.
     state0 = np.empty(size, np.float64)
-    mujoco.mj_getState(self.model, self.data, state0, spec)
+    mujoco.mj_getState(self.model, self.data, state0, sig)
 
     # Step, get next state.
     mujoco.mj_step(self.model, self.data)
     state1a = np.empty(size, np.float64)
-    mujoco.mj_getState(self.model, self.data, state1a, spec)
+    mujoco.mj_getState(self.model, self.data, state1a, sig)
 
     # Reset to initial state, step again, get state again.
-    mujoco.mj_setState(self.model, self.data, state0, spec)
+    mujoco.mj_setState(self.model, self.data, state0, sig)
     mujoco.mj_step(self.model, self.data)
     state1b = np.empty(size, np.float64)
-    mujoco.mj_getState(self.model, self.data, state1b, spec)
+    mujoco.mj_getState(self.model, self.data, state1b, sig)
 
     # Expect next states to be equal.
     np.testing.assert_array_equal(state1a, state1b)
@@ -805,7 +805,7 @@ class MuJoCoBindingsTest(parameterized.TestCase):
   def test_mj_setKeyframe(self):  # pylint: disable=invalid-name
     mujoco.mj_step(self.model, self.data)
 
-    # Test for invalid state spec
+    # Test for invalid keyframe
     invalid_key = 2
     expected_message = (
         f'mj_setKeyframe: index must be smaller than {invalid_key} (keyframes'

python/mujoco/functions.cc

@@ -292,20 +292,20 @@ PYBIND11_MODULE(_functions, pymodule) {
   Def<traits::mj_getState>(
       pymodule,
       [](const raw::MjModel* m, const raw::MjData* d,
-         Eigen::Ref<EigenVectorX> state, unsigned int spec) {
+         Eigen::Ref<EigenVectorX> state, unsigned int sig) {
-        if (state.size() != mj_stateSize(m, spec)) {
+        if (state.size() != mj_stateSize(m, sig)) {
-          throw py::type_error("state size should equal mj_stateSize(m, spec)");
+          throw py::type_error("state size should equal mj_stateSize(m, sig)");
         }
-        return InterceptMjErrors(::mj_getState)(m, d, state.data(), spec);
+        return InterceptMjErrors(::mj_getState)(m, d, state.data(), sig);
       });
   Def<traits::mj_setState>(
       pymodule,
       [](const raw::MjModel* m, raw::MjData* d,
-         const Eigen::Ref<EigenVectorX> state, unsigned int spec) {
+         const Eigen::Ref<EigenVectorX> state, unsigned int sig) {
-        if (state.size() != mj_stateSize(m, spec)) {
+        if (state.size() != mj_stateSize(m, sig)) {
-          throw py::type_error("state size should equal mj_stateSize(m, spec)");
+          throw py::type_error("state size should equal mj_stateSize(m, sig)");
         }
-        return InterceptMjErrors(::mj_setState)(m, d, state.data(), spec);
+        return InterceptMjErrors(::mj_setState)(m, d, state.data(), sig);
       });
   Def<traits::mj_setKeyframe>(pymodule);
   Def<traits::mj_addContact>(pymodule);

python/mujoco/introspect/functions.py

@@ -2226,11 +2226,11 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
                  ),
              ),
              FunctionParameterDecl(
-                 name='spec',
+                 name='sig',
                  type=ValueType(name='unsigned int'),
              ),
          ),
-         doc='Return size of state specification.',
+         doc='Return size of state signature.',
      )),
     ('mj_getState',
      FunctionDecl(
@@ -2256,7 +2256,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
                  ),
              ),
              FunctionParameterDecl(
-                 name='spec',
+                 name='sig',
                  type=ValueType(name='unsigned int'),
              ),
          ),
@@ -2286,7 +2286,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
                  ),
              ),
              FunctionParameterDecl(
-                 name='spec',
+                 name='sig',
                  type=ValueType(name='unsigned int'),
              ),
          ),

src/engine/engine_support.c

@@ -112,8 +112,8 @@ const int mjCONDATA_SIZE[mjNCONDATA] = {
 //-------------------------- get/set state ---------------------------------------------------------
 
 // return size of a single state element
-static inline int mj_stateElemSize(const mjModel* m, mjtState spec) {
+static inline int mj_stateElemSize(const mjModel* m, mjtState sig) {
-  switch (spec) {
+  switch (sig) {
   case mjSTATE_TIME:          return 1;
   case mjSTATE_QPOS:          return m->nq;
   case mjSTATE_QVEL:          return m->nv;
@@ -128,7 +128,7 @@ static inline int mj_stateElemSize(const mjModel* m, mjtState spec) {
   case mjSTATE_USERDATA:      return m->nuserdata;
   case mjSTATE_PLUGIN:        return m->npluginstate;
   default:
-    mjERROR("invalid state element %u", spec);
+    mjERROR("invalid state element %u", sig);
     return 0;
   }
 }
@@ -136,8 +136,8 @@ static inline int mj_stateElemSize(const mjModel* m, mjtState spec) {
 
 
 // return pointer to a single state element
-static inline mjtNum* mj_stateElemPtr(const mjModel* m, mjData* d, mjtState spec) {
+static inline mjtNum* mj_stateElemPtr(const mjModel* m, mjData* d, mjtState sig) {
-  switch (spec) {
+  switch (sig) {
   case mjSTATE_TIME:          return &d->time;
   case mjSTATE_QPOS:          return d->qpos;
   case mjSTATE_QVEL:          return d->qvel;
@@ -151,29 +151,29 @@ static inline mjtNum* mj_stateElemPtr(const mjModel* m, mjData* d, mjtState spec
   case mjSTATE_USERDATA:      return d->userdata;
   case mjSTATE_PLUGIN:        return d->plugin_state;
   default:
-    mjERROR("invalid state element %u", spec);
+    mjERROR("invalid state element %u", sig);
     return NULL;
   }
 }
 
 
 
-static inline const mjtNum* mj_stateElemConstPtr(const mjModel* m, const mjData* d, mjtState spec) {
+static inline const mjtNum* mj_stateElemConstPtr(const mjModel* m, const mjData* d, mjtState sig) {
-  return mj_stateElemPtr(m, (mjData*) d, spec);  // discard const qualifier from d
+  return mj_stateElemPtr(m, (mjData*) d, sig);  // discard const qualifier from d
 }
 
 
 
-// get size of state specification
+// get size of state signature
-int mj_stateSize(const mjModel* m, unsigned int spec) {
+int mj_stateSize(const mjModel* m, unsigned int sig) {
-  if (spec >= (1<<mjNSTATE)) {
+  if (sig >= (1<<mjNSTATE)) {
-    mjERROR("invalid state spec %u >= 2^mjNSTATE", spec);
+    mjERROR("invalid state signature %u >= 2^mjNSTATE", sig);
   }
 
   int size = 0;
   for (int i=0; i < mjNSTATE; i++) {
     mjtState element = 1<<i;
-    if (element & spec) {
+    if (element & sig) {
       size += mj_stateElemSize(m, element);
     }
   }
@@ -184,15 +184,15 @@ int mj_stateSize(const mjModel* m, unsigned int spec) {
 
 
 // get state
-void mj_getState(const mjModel* m, const mjData* d, mjtNum* state, unsigned int spec) {
+void mj_getState(const mjModel* m, const mjData* d, mjtNum* state, unsigned int sig) {
-  if (spec >= (1<<mjNSTATE)) {
+  if (sig >= (1<<mjNSTATE)) {
-    mjERROR("invalid state spec %u >= 2^mjNSTATE", spec);
+    mjERROR("invalid state signature %u >= 2^mjNSTATE", sig);
   }
 
   int adr = 0;
   for (int i=0; i < mjNSTATE; i++) {
     mjtState element = 1<<i;
-    if (element & spec) {
+    if (element & sig) {
       int size = mj_stateElemSize(m, element);
 
       // special handling of eq_active (mjtByte)
@@ -216,15 +216,15 @@ void mj_getState(const mjModel* m, const mjData* d, mjtNum* state, unsigned int
 
 
 // set state
-void mj_setState(const mjModel* m, mjData* d, const mjtNum* state, unsigned int spec) {
+void mj_setState(const mjModel* m, mjData* d, const mjtNum* state, unsigned int sig) {
-  if (spec >= (1<<mjNSTATE)) {
+  if (sig >= (1<<mjNSTATE)) {
-    mjERROR("invalid state spec %u >= 2^mjNSTATE", spec);
+    mjERROR("invalid state signature %u >= 2^mjNSTATE", sig);
   }
 
   int adr = 0;
   for (int i=0; i < mjNSTATE; i++) {
     mjtState element = 1<<i;
-    if (element & spec) {
+    if (element & sig) {
       int size = mj_stateElemSize(m, element);
 
       // special handling of eq_active (mjtByte)

src/engine/engine_support.h

@@ -35,14 +35,14 @@ MJAPI extern const int mjCONDATA_SIZE[mjNCONDATA];  // TODO(tassa): expose in pu
 
 //-------------------------- get/set state ---------------------------------------------------------
 
-// return size of state specification
+// return size of state signature
-MJAPI int mj_stateSize(const mjModel* m, unsigned int spec);
+MJAPI int mj_stateSize(const mjModel* m, unsigned int sig);
 
 // get state
-MJAPI void mj_getState(const mjModel* m, const mjData* d, mjtNum* state, unsigned int spec);
+MJAPI void mj_getState(const mjModel* m, const mjData* d, mjtNum* state, unsigned int sig);
 
 // set state
-MJAPI void mj_setState(const mjModel* m, mjData* d, const mjtNum* state, unsigned int spec);
+MJAPI void mj_setState(const mjModel* m, mjData* d, const mjtNum* state, unsigned int sig);
 
 // copy current state to the k-th model keyframe
 MJAPI void mj_setKeyframe(mjModel* m, const mjData* d, int k);

test/engine/engine_support_test.cc

@@ -706,16 +706,16 @@ TEST_F(SupportTest, GetSetStateStepEqual) {
   // take one step
   mj_step(model, data);
 
-  int spec = mjSTATE_INTEGRATION;
+  int signature = mjSTATE_INTEGRATION;
-  int size = mj_stateSize(model, spec);
+  int size = mj_stateSize(model, signature);
 
   // save the initial state and step
   vector<mjtNum> state0a(size);
-  mj_getState(model, data, state0a.data(), spec);
+  mj_getState(model, data, state0a.data(), signature);
 
   // get the initial state, expect equality
   vector<mjtNum> state0b(size);
-  mj_getState(model, data, state0b.data(), spec);
+  mj_getState(model, data, state0b.data(), signature);
   EXPECT_EQ(state0a, state0b);
 
   // take one step
@@ -723,16 +723,16 @@ TEST_F(SupportTest, GetSetStateStepEqual) {
 
   // save the resulting state
   vector<mjtNum> state1a(size);
-  mj_getState(model, data, state1a.data(), spec);
+  mj_getState(model, data, state1a.data(), signature);
 
   // expect the state to be different after stepping
   EXPECT_THAT(state0a, testing::Ne(state1a));
 
   // reset to the saved state, step again, get the resulting state
-  mj_setState(model, data, state0a.data(), spec);
+  mj_setState(model, data, state0a.data(), signature);
   mj_step(model, data);
   vector<mjtNum> state1b(size);
-  mj_getState(model, data, state1b.data(), spec);
+  mj_getState(model, data, state1b.data(), signature);
 
   // expect the state to be the same after re-stepping
   EXPECT_EQ(state1a, state1b);

unity/Runtime/Bindings/MjBindings.cs

@@ -6591,13 +6591,13 @@ public static unsafe extern void mj_referenceConstraint(mjModel_* m, mjData_* d)
 public static unsafe extern void mj_constraintUpdate(mjModel_* m, mjData_* d, double* jar, double* cost, int flg_coneHessian);
 
 [DllImport("mujoco", CallingConvention = CallingConvention.Cdecl)]
-public static unsafe extern int mj_stateSize(mjModel_* m, uint spec);
+public static unsafe extern int mj_stateSize(mjModel_* m, uint sig);
 
 [DllImport("mujoco", CallingConvention = CallingConvention.Cdecl)]
-public static unsafe extern void mj_getState(mjModel_* m, mjData_* d, double* state, uint spec);
+public static unsafe extern void mj_getState(mjModel_* m, mjData_* d, double* state, uint sig);
 
 [DllImport("mujoco", CallingConvention = CallingConvention.Cdecl)]
-public static unsafe extern void mj_setState(mjModel_* m, mjData_* d, double* state, uint spec);
+public static unsafe extern void mj_setState(mjModel_* m, mjData_* d, double* state, uint sig);
 
 [DllImport("mujoco", CallingConvention = CallingConvention.Cdecl)]
 public static unsafe extern void mj_setKeyframe(mjModel_* m, mjData_* d, int k);