Tighten task-space-accessor docstrings to focus on the contract

The base-class and per-backend property docstrings for the four new
task-space accessors had grown to include rationale prose, industry-
library citations, and implementation guidance for backend authors —
content that belongs in the PR description / changelog, not the API
documentation users read at code-completion time.

Trim each docstring to: shape + units + indexing convention + math
contract. Per-backend overrides defer to the base contract via
``See :attr:`BaseArticulationData.<name>``` and add only what's
specific to that backend (engine call used, any backend-only caveat).

No behavior change.

Author: hujc7

source/isaaclab/isaaclab/assets/articulation/base_articulation_data.py

@@ -628,108 +628,72 @@ def body_incoming_joint_wrench_b(self) -> ProxyArray:
     def body_link_jacobian_w(self) -> ProxyArray:
         """Per-body geometric Jacobian referenced at each body's link origin in world frame.
 
-        Shape is (num_instances, num_jacobi_bodies, 6, num_joints + num_base_dofs),
-        dtype = wp.float32. In torch this resolves to
-        (num_instances, num_jacobi_bodies, 6, num_joints + num_base_dofs).
-        Linear rows ``[0:3]`` [m/s for unit ``q_dot``], angular rows ``[3:6]`` [rad/s for unit
-        ``q_dot``].
+        Shape: ``(num_instances, num_jacobi_bodies, 6, num_joints + num_base_dofs)``,
+        dtype ``wp.float32``. Linear rows ``[0:3]`` [m/s per unit DoF velocity];
+        angular rows ``[3:6]`` [rad/s per unit DoF velocity].
 
-        For any generalized-velocity vector ``v`` of length ``num_joints + num_base_dofs``,
-        the returned Jacobian ``J`` satisfies:
+        Contract: for any generalized velocity ``v`` of length
+        ``num_joints + num_base_dofs``,
 
         .. code-block:: text
 
             J[:, jacobi_body_idx, 0:3, :] @ v == body_link_lin_vel_w[:, body_idx]
             J[:, jacobi_body_idx, 3:6, :] @ v == body_link_ang_vel_w[:, body_idx]
 
-        Linear rows ``[0:3]`` give the velocity at the link origin (the body's USD prim transform
-        / actor frame) in world frame. Angular rows ``[3:6]`` give the body's angular velocity in
-        world frame. The contract matches :attr:`body_link_pos_w` and :attr:`body_link_lin_vel_w`.
-        For fixed-base articulations, ``jacobi_body_idx`` excludes the fixed root body and is
-        therefore ``body_idx - 1``. For floating-base articulations, ``jacobi_body_idx ==
-        body_idx``.
-
-        Backends whose native Jacobian is expressed at the body center of mass MUST shift the
-        linear rows to the link origin before returning so the contract holds across backends.
-
-        The DoF axis prepends :attr:`~isaaclab.assets.BaseArticulation.num_base_dofs`
-        floating-base columns ([lin_x, lin_y, lin_z, ang_x, ang_y, ang_z] in world frame —
-        0 cols for fixed-base, 6 for floating-base), followed by the actuated-joint columns
-        in :attr:`joint_names` order. This matches the cross-library industry convention
-        (Pinocchio, Drake, MuJoCo, RBDL, OCS2, iDynTree). Consumers that index by actuated-
-        joint id should add ``num_base_dofs`` to the joint id.
+        Conventions:
+            * Body axis: ``jacobi_body_idx == body_idx - 1`` for fixed-base (fixed-root
+              row excluded); ``jacobi_body_idx == body_idx`` for floating-base.
+            * DoF axis: leading
+              :attr:`~isaaclab.assets.BaseArticulation.num_base_dofs` floating-base
+              columns (world-frame ``[lin_x, lin_y, lin_z, ang_x, ang_y, ang_z]``),
+              then actuated-joint columns in :attr:`joint_names` order.
         """
         raise NotImplementedError(f"{type(self).__name__} does not implement body_link_jacobian_w.")
 
     @property
     def body_com_jacobian_w(self) -> ProxyArray:
         """Per-body geometric Jacobian referenced at each body's center of mass in world frame.
 
-        Shape is (num_instances, num_jacobi_bodies, 6, num_joints + num_base_dofs),
-        dtype = wp.float32. In torch this resolves to
-        (num_instances, num_jacobi_bodies, 6, num_joints + num_base_dofs).
-        Linear rows ``[0:3]`` [m/s for unit ``q_dot``], angular rows ``[3:6]`` [rad/s for unit
-        ``q_dot``].
+        Same shape and indexing conventions as :attr:`body_link_jacobian_w`. Linear
+        rows ``[0:3]`` give the velocity at the body's center of mass; angular rows
+        ``[3:6]`` are reference-point invariant (identical to
+        :attr:`body_link_jacobian_w`).
 
-        For any generalized-velocity vector ``v`` of length ``num_joints + num_base_dofs``,
-        the returned Jacobian ``J`` satisfies:
+        Contract: for any generalized velocity ``v``,
 
         .. code-block:: text
 
             J[:, jacobi_body_idx, 0:3, :] @ v == body_com_lin_vel_w[:, body_idx]
             J[:, jacobi_body_idx, 3:6, :] @ v == body_com_ang_vel_w[:, body_idx]
-
-        Linear rows ``[0:3]`` give the velocity at the body's center of mass in world frame.
-        Angular rows ``[3:6]`` give the body's angular velocity in world frame (reference-point
-        invariant, identical to the angular rows of :attr:`body_link_jacobian_w`).
-
-        This is the form most physics engines compute natively, since dynamics equations decouple
-        at the COM. Use :attr:`body_link_jacobian_w` for IK / OSC controllers that target the
-        link-origin pose (USD prim frame).
-
-        DoF axis layout matches :attr:`body_link_jacobian_w`: leading
-        :attr:`~isaaclab.assets.BaseArticulation.num_base_dofs` floating-base columns,
-        followed by per-actuated-joint columns.
         """
         raise NotImplementedError(f"{type(self).__name__} does not implement body_com_jacobian_w.")
 
     @property
     def mass_matrix(self) -> ProxyArray:
-        """Per-env generalized mass matrix in joint space.
-
-        Shape is (num_instances, num_joints + num_base_dofs, num_joints + num_base_dofs),
-        dtype = wp.float32 [kg·m² or kg, depending on joint type]. In torch this resolves to
-        (num_instances, num_joints + num_base_dofs, num_joints + num_base_dofs).
+        """Per-env generalized mass matrix ``M(q)`` in joint space.
 
-        Returns the symmetric positive-definite inertia matrix ``M(q)`` of the articulation in
-        its generalized joint coordinates. ``M[i, j]`` is the coefficient relating DoF ``j``'s
-        acceleration to the inertial torque on DoF ``i`` in the equation of motion
-        ``M(q) q_ddot + C(q, q_dot) q_dot + g(q) = tau``. The matrix is reference-point
-        invariant — joint-space dynamics do not depend on whether body velocities are measured
-        at the COM or link origin.
+        Shape: ``(num_instances, num_joints + num_base_dofs, num_joints + num_base_dofs)``,
+        dtype ``wp.float32`` [kg·m² or kg, per DoF type]. DoF-axis convention matches
+        :attr:`body_link_jacobian_w`.
 
-        The DoF axis matches :attr:`body_link_jacobian_w`: leading
-        :attr:`~isaaclab.assets.BaseArticulation.num_base_dofs` floating-base rows/cols,
-        followed by per-actuated-joint rows/cols.
+        ``M(q)`` is symmetric positive-definite. ``M[i, j]`` is the coefficient
+        relating DoF ``j``'s acceleration to the inertial torque on DoF ``i`` in
+        ``M(q) q_ddot + C(q, q_dot) q_dot + g(q) = tau``.
         """
         raise NotImplementedError(f"{type(self).__name__} does not implement mass_matrix.")
 
     @property
     def gravity_compensation_forces(self) -> ProxyArray:
-        """Per-env gravity compensation torques in joint space.
+        """Per-env gravity compensation torques ``g(q)`` in joint space.
 
-        Shape is (num_instances, num_joints + num_base_dofs), dtype = wp.float32
-        [N·m or N, depending on joint type]. In torch this resolves to
-        (num_instances, num_joints + num_base_dofs).
+        Shape: ``(num_instances, num_joints + num_base_dofs)``, dtype ``wp.float32``
+        [N·m or N, per DoF type]. DoF-axis convention matches
+        :attr:`body_link_jacobian_w`.
 
-        Returns ``g(q)`` — the joint-space gravity-loading term in the equation of motion
+        ``g(q)`` is the gravity-loading term in
         ``M(q) q_ddot + C(q, q_dot) q_dot + g(q) = tau``. Applying ``tau = g(q)`` at
-        ``q_dot = 0`` with no external load yields ``q_ddot = 0`` (static equilibrium under
-        gravity).
-
-        The DoF axis matches :attr:`body_link_jacobian_w`: leading
-        :attr:`~isaaclab.assets.BaseArticulation.num_base_dofs` floating-base entries,
-        followed by per-actuated-joint entries.
+        ``q_dot = 0`` with no external load yields ``q_ddot = 0`` (static equilibrium
+        under gravity).
         """
         raise NotImplementedError(f"{type(self).__name__} does not implement gravity_compensation_forces.")
 

source/isaaclab_newton/isaaclab_newton/assets/articulation/articulation_data.py

@@ -838,22 +838,11 @@ def body_incoming_joint_wrench_b(self) -> ProxyArray:
 
     @property
     def body_com_jacobian_w(self) -> ProxyArray:
-        """Per-body geometric Jacobian referenced at each body's center of mass in world frame.
+        """See :attr:`isaaclab.assets.BaseArticulationData.body_com_jacobian_w`.
 
-        Shape is (num_instances, num_jacobi_bodies, 6, num_joints + num_base_dofs),
-        dtype = wp.float32. In torch this resolves to
-        (num_instances, num_jacobi_bodies, 6, num_joints + num_base_dofs).
-
-        Computed by ``eval_jacobian`` followed by a gather kernel that extracts this view's
-        rows / columns from the model-sized scratch buffer. Linear rows are referenced at the
-        body's center of mass; angular rows are reference-point invariant. Use
-        :attr:`body_link_jacobian_w` for IK / OSC controllers that target the link-origin pose.
-
-        For floating-base articulations the leading 6 columns correspond to the floating-base
-        spatial velocity in world frame (``[lin_x, lin_y, lin_z, ang_x, ang_y, ang_z]``); for
-        fixed-base articulations there are 0 base columns. Consumers that index by actuated-
-        joint id should add :attr:`~isaaclab.assets.BaseArticulation.num_base_dofs` to the
-        joint id.
+        Newton implementation: ``eval_jacobian`` (writes the model-wide buffer) then a
+        gather kernel extracts this view's rows. ``link_offset`` drops Newton's fixed-
+        root row for fixed-base; the DoF axis is preserved in full.
         """
         # Newton's eval_jacobian reads ``state.body_q`` (link poses); refresh FK if stale.
         # Matches the convention in ``body_link_pose_w`` — Python-guarded lazy refresh.
@@ -882,21 +871,10 @@ def body_com_jacobian_w(self) -> ProxyArray:
 
     @property
     def body_link_jacobian_w(self) -> ProxyArray:
-        """Per-body geometric Jacobian referenced at each body's link origin in world frame.
-
-        Shape is (num_instances, num_jacobi_bodies, 6, num_joints + num_base_dofs),
-        dtype = wp.float32. In torch this resolves to
-        (num_instances, num_jacobi_bodies, 6, num_joints + num_base_dofs).
+        """See :attr:`isaaclab.assets.BaseArticulationData.body_link_jacobian_w`.
 
-        Computed by applying the COM→origin shift to :attr:`body_com_jacobian_w`. The shift
-        identity ``v_origin = v_com - omega x (R · body_com_pos_b)`` is applied per-column
-        (each Jacobian column is one DoF's spatial-velocity contribution to a body). Angular
-        rows are unchanged; linear rows are shifted so the contract
-        ``J · q_dot[body_idx] == body_link_lin_vel_w[body_idx]`` holds.
-
-        Column layout matches :attr:`body_com_jacobian_w`: leading
-        :attr:`~isaaclab.assets.BaseArticulation.num_base_dofs` columns hold the floating-
-        base spatial velocity (0 for fixed-base), followed by per-actuated-joint columns.
+        Newton implementation: applies the COM→origin shift kernel to
+        :attr:`body_com_jacobian_w` (Newton's ``eval_jacobian`` is COM-referenced).
         """
         # ``body_link_pose_w`` accessor triggers ``SimulationManager.forward()`` if FK is
         # stale (after a manual joint / root write that bypassed the sim step). Reading the
@@ -920,16 +898,10 @@ def body_link_jacobian_w(self) -> ProxyArray:
 
     @property
     def mass_matrix(self) -> ProxyArray:
-        """Per-env generalized mass matrix in joint space.
-
-        Shape is (num_instances, num_joints + num_base_dofs, num_joints + num_base_dofs),
-        dtype = wp.float32. In torch this resolves to
-        (num_instances, num_joints + num_base_dofs, num_joints + num_base_dofs).
+        """See :attr:`isaaclab.assets.BaseArticulationData.mass_matrix`.
 
-        Returns the symmetric positive-definite inertia matrix ``M(q)`` of the articulation in
-        its generalized joint coordinates. For floating-base articulations the leading 6 rows
-        and columns correspond to the floating-base spatial velocity in world frame; for
-        fixed-base articulations there are 0 such rows/cols.
+        Newton implementation: ``eval_mass_matrix`` (writes the model-wide buffer) then a
+        gather kernel extracts this view's rows.
         """
         # eval_jacobian / eval_mass_matrix read ``state.body_q``; refresh FK if stale.
         # Matches the convention in ``body_link_pose_w`` — Python-guarded lazy refresh.
@@ -965,12 +937,12 @@ def mass_matrix(self) -> ProxyArray:
 
     @property
     def gravity_compensation_forces(self) -> ProxyArray:
-        """Per-env gravity compensation torques in joint space.
+        """See :attr:`isaaclab.assets.BaseArticulationData.gravity_compensation_forces`.
 
-        Newton's ArticulationView has no ``eval_gravity_compensation`` primitive (only
-        ``eval_fk`` / ``eval_jacobian`` / ``eval_mass_matrix``). Callers that need gravity
-        compensation must run on PhysX, or set the controller's ``gravity_compensation`` flag
-        to ``False`` until upstream Newton adds the missing API.
+        Newton implementation: raises :class:`NotImplementedError` — Newton's
+        ``ArticulationView`` exposes only ``eval_fk`` / ``eval_jacobian`` /
+        ``eval_mass_matrix``. Use PhysX, or set the controller's
+        ``gravity_compensation=False`` until upstream Newton adds the primitive.
         """
         raise NotImplementedError(
             "Newton has no gravity-compensation primitive. Use PhysX, or set the controller's"

source/isaaclab_physx/isaaclab_physx/assets/articulation/articulation_data.py

@@ -883,41 +883,19 @@ def body_incoming_joint_wrench_b(self) -> ProxyArray:
 
     @property
     def body_com_jacobian_w(self) -> ProxyArray:
-        """Per-body geometric Jacobian referenced at each body's center of mass in world frame.
+        """See :attr:`isaaclab.assets.BaseArticulationData.body_com_jacobian_w`.
 
-        Shape is (num_instances, num_jacobi_bodies, 6, num_joints + num_base_dofs),
-        dtype = wp.float32. In torch this resolves to
-        (num_instances, num_jacobi_bodies, 6, num_joints + num_base_dofs).
-
-        Linear rows are referenced at the body's center of mass; angular rows are
-        reference-point invariant. Use :attr:`body_link_jacobian_w` for IK / OSC controllers
-        that target the link-origin pose.
-
-        For floating-base articulations the leading 6 columns correspond to the floating-base
-        spatial velocity in world frame (``[lin_x, lin_y, lin_z, ang_x, ang_y, ang_z]``); for
-        fixed-base articulations there are 0 base columns. Consumers that index by actuated-
-        joint id should add :attr:`~isaaclab.assets.BaseArticulation.num_base_dofs` to the
-        joint id.
+        PhysX implementation: passthrough of ``_root_view.get_jacobians()``, which is
+        natively COM-referenced.
         """
         return ProxyArray(self._root_view.get_jacobians())
 
     @property
     def body_link_jacobian_w(self) -> ProxyArray:
-        """Per-body geometric Jacobian referenced at each body's link origin in world frame.
-
-        Shape is (num_instances, num_jacobi_bodies, 6, num_joints + num_base_dofs),
-        dtype = wp.float32. In torch this resolves to
-        (num_instances, num_jacobi_bodies, 6, num_joints + num_base_dofs).
+        """See :attr:`isaaclab.assets.BaseArticulationData.body_link_jacobian_w`.
 
-        Computed by applying the COM→origin shift to :attr:`body_com_jacobian_w`. The shift
-        identity ``v_origin = v_com - omega x (R · body_com_pos_b)`` is applied per-column
-        (each Jacobian column is one DoF's spatial-velocity contribution to a body). Angular
-        rows are unchanged; linear rows are shifted from COM to link origin so the contract
-        ``J · q_dot[body_idx] == body_link_lin_vel_w[body_idx]`` holds.
-
-        Column layout matches :attr:`body_com_jacobian_w`: leading
-        :attr:`~isaaclab.assets.BaseArticulation.num_base_dofs` columns hold the floating-
-        base spatial velocity (0 for fixed-base), followed by per-actuated-joint columns.
+        PhysX implementation: applies the COM→origin shift kernel to
+        :attr:`body_com_jacobian_w` (PhysX's engine output is COM-referenced).
         """
         wp.launch(
             articulation_kernels.shift_jacobian_com_to_origin,
@@ -935,31 +913,17 @@ def body_link_jacobian_w(self) -> ProxyArray:
 
     @property
     def mass_matrix(self) -> ProxyArray:
-        """Per-env generalized mass matrix in joint space.
-
-        Shape is (num_instances, num_joints + num_base_dofs, num_joints + num_base_dofs),
-        dtype = wp.float32. In torch this resolves to
-        (num_instances, num_joints + num_base_dofs, num_joints + num_base_dofs).
+        """See :attr:`isaaclab.assets.BaseArticulationData.mass_matrix`.
 
-        Returns the symmetric positive-definite inertia matrix ``M(q)`` of the articulation in
-        its generalized joint coordinates. For floating-base articulations the leading 6 rows
-        and columns correspond to the floating-base spatial velocity in world frame; for
-        fixed-base articulations there are 0 such rows/cols.
+        PhysX implementation: passthrough of ``_root_view.get_generalized_mass_matrices()``.
         """
         return ProxyArray(self._root_view.get_generalized_mass_matrices())
 
     @property
     def gravity_compensation_forces(self) -> ProxyArray:
-        """Per-env gravity compensation torques in joint space.
-
-        Shape is (num_instances, num_joints + num_base_dofs), dtype = wp.float32
-        [N·m or N, depending on joint type]. In torch this resolves to
-        (num_instances, num_joints + num_base_dofs).
+        """See :attr:`isaaclab.assets.BaseArticulationData.gravity_compensation_forces`.
 
-        Returns ``g(q)`` — the joint-space gravity-loading term in the equation of motion
-        ``M(q) q_ddot + C(q, q_dot) q_dot + g(q) = tau``. For floating-base articulations the
-        leading 6 entries correspond to the floating-base spatial velocity in world frame; for
-        fixed-base articulations there are 0 such entries.
+        PhysX implementation: passthrough of ``_root_view.get_gravity_compensation_forces()``.
         """
         return ProxyArray(self._root_view.get_gravity_compensation_forces())