Merge branch 'develop' into offline_mode

Author: clayton-littlejohn

docs/source/migration/migrating_to_isaaclab_3-0.rst

@@ -571,6 +571,209 @@ quaternions in XYZW format:
 - And all other quaternion utilities
 
 
+Warp Backend for Asset and Sensor Data
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All ``.data.*`` properties on asset and sensor classes now return ``wp.array`` instead of
+``torch.Tensor``. This change applies to all asset classes (:class:`~isaaclab.assets.Articulation`,
+:class:`~isaaclab.assets.RigidObject`, :class:`~isaaclab.assets.RigidObjectCollection`,
+:class:`~isaaclab_physx.assets.DeformableObject`) and all sensor classes
+(:class:`~isaaclab_physx.sensors.ContactSensor`, :class:`~isaaclab_physx.sensors.Imu`,
+:class:`~isaaclab_physx.sensors.FrameTransformer`).
+
+To convert back to ``torch.Tensor`` for use with PyTorch operations, wrap the property
+access with ``wp.to_torch()``:
+
+.. code-block:: python
+
+   import warp as wp
+
+   # Before (Isaac Lab 2.x)
+   root_pos = robot.data.root_pos_w             # torch.Tensor
+   joint_pos = robot.data.joint_pos              # torch.Tensor
+   contact_forces = sensor.data.net_forces_w     # torch.Tensor
+
+   # After (Isaac Lab 3.x)
+   root_pos = robot.data.root_pos_w              # wp.array
+   joint_pos = robot.data.joint_pos              # wp.array
+   contact_forces = sensor.data.net_forces_w     # wp.array
+
+   # To use with torch operations, wrap with wp.to_torch()
+   root_pos_torch = wp.to_torch(robot.data.root_pos_w)        # torch.Tensor
+   joint_pos_torch = wp.to_torch(robot.data.joint_pos)        # torch.Tensor
+   contact_torch = wp.to_torch(sensor.data.net_forces_w)      # torch.Tensor
+
+Common patterns that need updating:
+
+.. code-block:: python
+
+   # Cloning data
+   # Before:
+   pos = robot.data.root_pos_w.clone()
+   # After:
+   pos = wp.to_torch(robot.data.root_pos_w).clone()
+
+   # Creating zero tensors with matching shape
+   # Before:
+   zeros = torch.zeros_like(robot.data.root_pos_w)
+   # After:
+   zeros = torch.zeros_like(wp.to_torch(robot.data.root_pos_w))
+
+   # Assertions in tests
+   # Before:
+   torch.testing.assert_close(robot.data.root_pos_w, expected)
+   # After:
+   torch.testing.assert_close(wp.to_torch(robot.data.root_pos_w), expected)
+
+.. list-table:: Affected classes
+   :header-rows: 1
+   :widths: 40 60
+
+   * - Class
+     - Package
+   * - :class:`~isaaclab.assets.Articulation`
+     - ``isaaclab`` / ``isaaclab_physx``
+   * - :class:`~isaaclab.assets.RigidObject`
+     - ``isaaclab`` / ``isaaclab_physx``
+   * - :class:`~isaaclab.assets.RigidObjectCollection`
+     - ``isaaclab`` / ``isaaclab_physx``
+   * - :class:`~isaaclab_physx.assets.DeformableObject`
+     - ``isaaclab_physx``
+   * - :class:`~isaaclab_physx.sensors.ContactSensor`
+     - ``isaaclab_physx``
+   * - :class:`~isaaclab_physx.sensors.Imu`
+     - ``isaaclab_physx``
+   * - :class:`~isaaclab_physx.sensors.FrameTransformer`
+     - ``isaaclab_physx``
+
+.. note::
+
+   An automated migration tool is provided at ``scripts/tools/wrap_warp_to_torch.py``.
+   It scans Python files for ``.data.<property>`` accesses and wraps them with
+   ``wp.to_torch()``. Usage:
+
+   .. code-block:: bash
+
+      # Dry run (preview changes)
+      python scripts/tools/wrap_warp_to_torch.py path/to/your/code --dry-run
+
+      # Apply changes in-place
+      python scripts/tools/wrap_warp_to_torch.py path/to/your/code
+
+   Always review the changes after running the tool, as some accesses (e.g., those
+   already passed to warp-native functions) should not be wrapped.
+
+
+Write Method Index/Mask Split
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All asset write methods have been split into two explicit variants:
+
+- ``write_*_to_sim_index(data, env_ids)`` — accepts partial data for a sparse set of
+  environment indices. The ``data`` tensor has shape ``(len(env_ids), ...)``.
+- ``write_*_to_sim_mask(data, env_mask)`` — accepts full data for all environments with a
+  boolean mask selecting which environments to update. The ``data`` tensor has shape
+  ``(num_envs, ...)``.
+
+The previous ``write_*_to_sim(data, env_ids)`` methods have been removed.
+
+.. code-block:: python
+
+   # Before (Isaac Lab 2.x)
+   robot.write_root_pose_to_sim(pose_data, env_ids)
+
+   # After (Isaac Lab 3.x) — indexed variant (partial data)
+   robot.write_root_pose_to_sim_index(pose_data, env_ids)
+
+   # After (Isaac Lab 3.x) — mask variant (full data, boolean mask)
+   robot.write_root_pose_to_sim_mask(pose_data, env_mask)
+
+.. list-table:: Affected write methods (RigidObject / Articulation)
+   :header-rows: 1
+   :widths: 50 50
+
+   * - Old method
+     - New methods
+   * - ``write_root_pose_to_sim``
+     - ``write_root_pose_to_sim_index`` / ``write_root_pose_to_sim_mask``
+   * - ``write_root_link_pose_to_sim``
+     - ``write_root_link_pose_to_sim_index`` / ``write_root_link_pose_to_sim_mask``
+   * - ``write_root_com_pose_to_sim``
+     - ``write_root_com_pose_to_sim_index`` / ``write_root_com_pose_to_sim_mask``
+   * - ``write_root_velocity_to_sim``
+     - ``write_root_velocity_to_sim_index`` / ``write_root_velocity_to_sim_mask``
+   * - ``write_root_com_velocity_to_sim``
+     - ``write_root_com_velocity_to_sim_index`` / ``write_root_com_velocity_to_sim_mask``
+   * - ``write_root_link_velocity_to_sim``
+     - ``write_root_link_velocity_to_sim_index`` / ``write_root_link_velocity_to_sim_mask``
+
+.. list-table:: Additional Articulation-specific write methods
+   :header-rows: 1
+   :widths: 50 50
+
+   * - Old method
+     - New methods
+   * - ``write_joint_position_to_sim``
+     - ``write_joint_position_to_sim_index`` / ``write_joint_position_to_sim_mask``
+   * - ``write_joint_velocity_to_sim``
+     - ``write_joint_velocity_to_sim_index`` / ``write_joint_velocity_to_sim_mask``
+   * - ``write_joint_stiffness_to_sim``
+     - ``write_joint_stiffness_to_sim_index`` / ``write_joint_stiffness_to_sim_mask``
+   * - ``write_joint_damping_to_sim``
+     - ``write_joint_damping_to_sim_index`` / ``write_joint_damping_to_sim_mask``
+   * - ``write_joint_position_limit_to_sim``
+     - ``write_joint_position_limit_to_sim_index`` / ``write_joint_position_limit_to_sim_mask``
+   * - ``write_joint_velocity_limit_to_sim``
+     - ``write_joint_velocity_limit_to_sim_index`` / ``write_joint_velocity_limit_to_sim_mask``
+   * - ``write_joint_effort_limit_to_sim``
+     - ``write_joint_effort_limit_to_sim_index`` / ``write_joint_effort_limit_to_sim_mask``
+   * - ``write_joint_armature_to_sim``
+     - ``write_joint_armature_to_sim_index`` / ``write_joint_armature_to_sim_mask``
+   * - ``write_joint_friction_coefficient_to_sim``
+     - ``write_joint_friction_coefficient_to_sim_index`` / ``write_joint_friction_coefficient_to_sim_mask``
+
+.. list-table:: RigidObjectCollection write methods
+   :header-rows: 1
+   :widths: 50 50
+
+   * - Old method
+     - New methods
+   * - ``write_body_pose_to_sim``
+     - ``write_body_pose_to_sim_index`` / ``write_body_pose_to_sim_mask``
+   * - ``write_body_link_pose_to_sim``
+     - ``write_body_link_pose_to_sim_index`` / ``write_body_link_pose_to_sim_mask``
+   * - ``write_body_com_pose_to_sim``
+     - ``write_body_com_pose_to_sim_index`` / ``write_body_com_pose_to_sim_mask``
+   * - ``write_body_velocity_to_sim``
+     - ``write_body_velocity_to_sim_index`` / ``write_body_velocity_to_sim_mask``
+   * - ``write_body_com_velocity_to_sim``
+     - ``write_body_com_velocity_to_sim_index`` / ``write_body_com_velocity_to_sim_mask``
+   * - ``write_body_link_velocity_to_sim``
+     - ``write_body_link_velocity_to_sim_index`` / ``write_body_link_velocity_to_sim_mask``
+
+
+TimestampedBufferWarp
+~~~~~~~~~~~~~~~~~~~~~
+
+If you have custom asset or sensor data classes that subclass the Isaac Lab base data classes,
+note that internal buffers have changed from :class:`~isaaclab.utils.buffers.TimestampedBuffer`
+to :class:`~isaaclab.utils.buffers.TimestampedBufferWarp`. The new class takes ``(shape, device,
+wp_dtype)`` as constructor arguments instead of a ``torch.Tensor``:
+
+.. code-block:: python
+
+   import warp as wp
+   from isaaclab.utils.buffers import TimestampedBufferWarp
+
+   # Before (Isaac Lab 2.x)
+   self._data.root_pos_w = TimestampedBuffer(torch.zeros(num_envs, 3, device=device))
+
+   # After (Isaac Lab 3.x)
+   self._data.root_pos_w = TimestampedBufferWarp(
+       shape=(num_envs,), device=device, wp_dtype=wp.vec3f
+   )
+
+
 Need Help?
 ~~~~~~~~~~
 

docs/source/tutorials/01_assets/run_deformable_object.rst

@@ -149,7 +149,7 @@ the average position of all the nodes in the mesh.
 .. literalinclude:: ../../../../scripts/tutorials/01_assets/run_deformable_object.py
    :language: python
    :start-at: # update buffers
-   :end-at: print(f"Root position (in world): {cube_object.data.root_pos_w[:, :3]}")
+   :end-at: print(f"Root position (in world): {wp.to_torch(cube_object.data.root_pos_w)[:, :3]}")
 
 
 The Code Execution

scripts/benchmarks/benchmark_load_robot.py

@@ -57,6 +57,7 @@
 imports_time_begin = time.perf_counter_ns()
 
 import torch
+import warp as wp
 
 import isaaclab.sim as sim_utils
 from isaaclab.assets import ArticulationCfg, AssetBaseCfg
@@ -133,19 +134,22 @@ def run_simulator(sim: sim_utils.SimulationContext, scene: InteractiveScene):
             # root state
             # we offset the root state by the origin since the states are written in simulation world frame
             # if this is not done, then the robots will be spawned at the (0, 0, 0) of the simulation world
-            root_state = robot.data.default_root_state.clone()
+            root_state = wp.to_torch(robot.data.default_root_state).clone()
             root_state[:, :3] += scene.env_origins
             robot.write_root_pose_to_sim(root_state[:, :7])
             robot.write_root_velocity_to_sim(root_state[:, 7:])
             # set joint positions with some noise
-            joint_pos, joint_vel = robot.data.default_joint_pos.clone(), robot.data.default_joint_vel.clone()
+            joint_pos, joint_vel = (
+                wp.to_torch(robot.data.default_joint_pos).clone(),
+                wp.to_torch(robot.data.default_joint_vel).clone(),
+            )
             joint_pos += torch.rand_like(joint_pos) * 0.1
             robot.write_joint_state_to_sim(joint_pos, joint_vel)
             # clear internal buffers
             scene.reset()
         # Apply random action
         # -- generate random joint efforts
-        efforts = torch.randn_like(robot.data.joint_pos) * 5.0
+        efforts = torch.randn_like(wp.to_torch(robot.data.joint_pos)) * 5.0
         # -- apply action to the robot
         robot.set_joint_effort_target(efforts)
         # -- write data to sim

scripts/demos/arms.py

@@ -34,6 +34,7 @@
 
 import numpy as np
 import torch
+import warp as wp
 
 import isaaclab.sim as sim_utils
 from isaaclab.assets import Articulation
@@ -188,10 +189,11 @@ def run_simulator(sim: sim_utils.SimulationContext, entities: dict[str, Articula
         # apply random actions to the robots
         for robot in entities.values():
             # generate random joint positions
-            joint_pos_target = robot.data.default_joint_pos + torch.randn_like(robot.data.joint_pos) * 0.1
-            joint_pos_target = joint_pos_target.clamp_(
-                robot.data.soft_joint_pos_limits[..., 0], robot.data.soft_joint_pos_limits[..., 1]
+            joint_pos_target = (
+                wp.to_torch(robot.data.default_joint_pos) + torch.randn_like(wp.to_torch(robot.data.joint_pos)) * 0.1
             )
+            soft_limits = wp.to_torch(robot.data.soft_joint_pos_limits)
+            joint_pos_target = joint_pos_target.clamp_(soft_limits[..., 0], soft_limits[..., 1])
             # apply action to the robot
             robot.set_joint_position_target(joint_pos_target)
             # write data to sim

scripts/demos/bipeds.py

@@ -33,6 +33,7 @@
 """Rest everything follows."""
 
 import torch
+import warp as wp
 
 import isaaclab.sim as sim_utils
 from isaaclab.assets import Articulation
@@ -88,9 +89,12 @@ def run_simulator(sim: sim_utils.SimulationContext, robots: list[Articulation],
             count = 0
             for index, robot in enumerate(robots):
                 # reset dof state
-                joint_pos, joint_vel = robot.data.default_joint_pos, robot.data.default_joint_vel
+                joint_pos, joint_vel = (
+                    wp.to_torch(robot.data.default_joint_pos),
+                    wp.to_torch(robot.data.default_joint_vel),
+                )
                 robot.write_joint_state_to_sim(joint_pos, joint_vel)
-                root_state = robot.data.default_root_state.clone()
+                root_state = wp.to_torch(robot.data.default_root_state).clone()
                 root_state[:, :3] += origins[index]
                 robot.write_root_pose_to_sim(root_state[:, :7])
                 robot.write_root_velocity_to_sim(root_state[:, 7:])
@@ -99,7 +103,7 @@ def run_simulator(sim: sim_utils.SimulationContext, robots: list[Articulation],
             print(">>>>>>>> Reset!")
         # apply action to the robot
         for robot in robots:
-            robot.set_joint_position_target(robot.data.default_joint_pos.clone())
+            robot.set_joint_position_target(wp.to_torch(robot.data.default_joint_pos).clone())
             robot.write_data_to_sim()
         # perform step
         sim.step()

scripts/demos/deformables.py

@@ -36,6 +36,7 @@
 import numpy as np
 import torch
 import tqdm
+import warp as wp
 
 import isaaclab.sim as sim_utils
 from isaaclab.assets import DeformableObject, DeformableObjectCfg
@@ -160,7 +161,7 @@ def run_simulator(sim: sim_utils.SimulationContext, entities: dict[str, Deformab
             # reset deformable object state
             for _, deform_body in enumerate(entities.values()):
                 # root state
-                nodal_state = deform_body.data.default_nodal_state_w.clone()
+                nodal_state = wp.to_torch(deform_body.data.default_nodal_state_w).clone()
                 deform_body.write_nodal_state_to_sim(nodal_state)
                 # reset the internal state
                 deform_body.reset()

scripts/demos/h1_locomotion.py

@@ -43,6 +43,7 @@
 """Rest everything follows."""
 
 import torch
+import warp as wp
 from rsl_rl.runners import OnPolicyRunner
 
 import carb
@@ -196,8 +197,10 @@ def _update_camera(self):
         """Updates the per-frame transform of the third-person view camera to follow
         the selected robot's torso transform."""
 
-        base_pos = self.env.unwrapped.scene["robot"].data.root_pos_w[self._selected_id, :]  # - env.scene.env_origins
-        base_quat = self.env.unwrapped.scene["robot"].data.root_quat_w[self._selected_id, :]
+        base_pos = wp.to_torch(self.env.unwrapped.scene["robot"].data.root_pos_w)[
+            self._selected_id, :
+        ]  # - env.scene.env_origins
+        base_quat = wp.to_torch(self.env.unwrapped.scene["robot"].data.root_quat_w)[self._selected_id, :]
 
         camera_pos = quat_apply(base_quat, self._camera_local_transform) + base_pos
 

scripts/demos/hands.py

@@ -34,6 +34,7 @@
 
 import numpy as np
 import torch
+import warp as wp
 
 import isaaclab.sim as sim_utils
 from isaaclab.assets import Articulation
@@ -109,12 +110,15 @@ def run_simulator(sim: sim_utils.SimulationContext, entities: dict[str, Articula
             # reset robots
             for index, robot in enumerate(entities.values()):
                 # root state
-                root_state = robot.data.default_root_state.clone()
+                root_state = wp.to_torch(robot.data.default_root_state).clone()
                 root_state[:, :3] += origins[index]
                 robot.write_root_pose_to_sim(root_state[:, :7])
                 robot.write_root_velocity_to_sim(root_state[:, 7:])
                 # joint state
-                joint_pos, joint_vel = robot.data.default_joint_pos.clone(), robot.data.default_joint_vel.clone()
+                joint_pos, joint_vel = (
+                    wp.to_torch(robot.data.default_joint_pos).clone(),
+                    wp.to_torch(robot.data.default_joint_vel).clone(),
+                )
                 robot.write_joint_state_to_sim(joint_pos, joint_vel)
                 # reset the internal state
                 robot.reset()
@@ -125,7 +129,7 @@ def run_simulator(sim: sim_utils.SimulationContext, entities: dict[str, Articula
         # apply default actions to the hands robots
         for robot in entities.values():
             # generate joint positions
-            joint_pos_target = robot.data.soft_joint_pos_limits[..., grasp_mode]
+            joint_pos_target = wp.to_torch(robot.data.soft_joint_pos_limits)[..., grasp_mode]
             # apply action to the robot
             robot.set_joint_position_target(joint_pos_target)
             # write data to sim