使用 ProxyArray

使用 ProxyArray#

Isaac Lab 数据类返回 ProxyArray ，这是以 Warp 为基础的轻量封装，可将仿真数据作为 warp.array 或 torch.Tensor 零拷贝访问。

备注

ProxyArray 的设计参考了 mujocolab/mjlab 中的 ProxyArray 类（BSD-3-Clause 许可），将同样的双访问器模式用于 Isaac Lab 基于 Warp 的数据管线。

快速开始#

资产和传感器数据类的每个属性，例如 robot.data.joint_pos 、 sensor.data.net_normal_forces_w ，都会返回 ProxyArray ：

robot = env.scene["robot"]

# Explicit torch access (preferred)
joint_positions = robot.data.joint_pos.torch        # torch.Tensor, cached zero-copy view
gravity_proj = robot.data.projected_gravity_b.torch  # torch.Tensor

# Explicit warp access (for kernel interop)
wp_array = robot.data.joint_pos.warp                # warp.array, the original buffer

# Pass directly to warp kernels — no unwrapping needed
wp.launch(my_kernel, inputs=[robot.data.joint_pos], ...)  # works via __cuda_array_interface__

.torch 与 .warp 访问器#

  • .torch 通过 warp.to_torch() ，返回底层 Warp 数组的缓存式零拷贝 torch.Tensor 视图。张量在首次访问时创建，后续调用复用。由于是零拷贝视图，修改张量也会反映在 Warp 数组中，反之亦然。

  • .warp 返回原始 warp.array 。需要显式向 Warp 核函数传入数据，或访问 ptr 、 strides 等 Warp 专用属性时，使用此访问器。

弃用过渡兼容机制#

为方便迁移， ProxyArray 提供弃用过渡兼容机制，让旧代码可以暂时将其当作 torch.Tensor 使用：

# These still work but emit a one-time DeprecationWarning:
result = torch.sum(robot.data.joint_pos)           # via __torch_function__
value = robot.data.joint_pos[0, 3]                 # via __getitem__
result = robot.data.joint_pos + 1.0                # via __add__
legacy = wp.to_torch(robot.data.joint_pos)         # temporary shim

# Preferred (no warning):
result = torch.sum(robot.data.joint_pos.torch)
value = robot.data.joint_pos.torch[0, 3]
result = robot.data.joint_pos.torch + 1.0
tensor = robot.data.joint_pos.torch

wp.to_torch() 兼容路径是临时适配层，用于在 ProxyArray 提供显式访问器之前已迁移的代码。它返回与 .torch 相同的零拷贝张量，并发出一次 DeprecationWarning 。此适配层和其他弃用兼容机制将在后续版本移除。请现在迁移到显式 .torch 访问。

从 Isaac Lab 2.x 迁移#

Isaac Lab 2.x 的数据属性直接返回 torch.Tensor ；3.0 则返回 ProxyArray 。追加 .torch 即可获取张量：

# BEFORE (Isaac Lab 2.x) — properties returned torch.Tensor directly
joint_pos = robot.data.joint_pos
first_contact = sensor.compute_first_contact(dt)

# AFTER (Isaac Lab 3.0) — properties return ProxyArray
joint_pos = robot.data.joint_pos.torch
first_contact = sensor.compute_first_contact(dt).torch

备注

临时兼容层允许向 wp.to_torch() 传入 ProxyArray ，返回与 .torch 相同的缓存式零拷贝张量。该路径会发出一次 DeprecationWarning ，并将在后续版本移除。新代码应使用 .torch 。

后端差异#

各后端的 ProxyArray 接口相同，但底层数据刷新方式不同：

PhysX（访问时拉取刷新）：

每个仿真步中首次访问属性时，会从 PhysX 张量 API 拉取最新数据并缓存结果。底层 GPU 缓冲区稳定且已预分配，因此 ProxyArray 封装只创建一次，可安全地跨步复用。

Newton（自动刷新并替换封装）：

仿真每步自动刷新 GPU 缓冲区。完整仿真重置时，可能重新创建缓冲区。Newton 后端会为新的 Warp 数组创建新的 ProxyArray 封装，使此前缓存的 Torch 张量失效。

两种情况下， .torch 始终返回当前步中当前仿真状态的视图。

警告

不要跨仿真重置缓存 .torch 的结果。重置后（尤其是 Newton），此前获取的张量可能指向过时或已释放的 GPU 内存。重置后务必重新访问属性。

API 参考#

class isaaclab.utils.warp.ProxyArray[源代码]

Warp-first array wrapper providing cached zero-copy .torch and .warp accessors.

This class wraps a warp.array and provides:

  • A .warp property that returns the original warp array (for kernel interop).

  • A .torch property that returns a cached, zero-copy torch.Tensor view (via warp.to_torch()).

  • Convenience properties (shape, dtype, device) delegated to the warp array.

  • A deprecation bridge for common torch functions, indexing, and arithmetic/comparison operators while emitting a one-time DeprecationWarning. Tensor instance methods such as clone() are not forwarded; use explicit .torch access for those.

Example:

import warp as wp
from isaaclab.utils.warp.proxy_array import ProxyArray

arr = wp.zeros(100, dtype=wp.vec3f, device="cuda:0")
ta = ProxyArray(arr)

# Explicit access (preferred)
ta.warp  # -> wp.array, shape (100,), dtype vec3f
ta.torch  # -> torch.Tensor, shape (100, 3)

# Deprecation bridge (warns once, then silent)
result = ta + 1.0  # works, emits DeprecationWarning

Methods:

__init__(wp_array)

Initialize the ProxyArray wrapper.

Attributes:

warp

The underlying warp array.

torch

A cached, zero-copy torch.Tensor view of the warp array.

shape

Shape of the underlying warp array.

dtype

Warp dtype of the underlying array.

device

Device string of the underlying warp array.
__init__(wp_array: warp.array) → None[源代码]

Initialize the ProxyArray wrapper.

The instance is immutable after construction: the wrapped wp.array cannot be reassigned. If the underlying simulation memory is re-allocated, construct a new ProxyArray instead of mutating an existing one.

参数:

wp_array -- The warp array to wrap.

抛出:

TypeError -- If wp_array is not a warp.array.

property warp: warp.array[源代码]

The underlying warp array.

property torch: torch.Tensor[源代码]

A cached, zero-copy torch.Tensor view of the warp array.

The tensor is created on first access and cached for subsequent calls. Since this is a zero-copy view, modifications to the tensor are visible through the warp array and vice versa.

When the underlying warp array has dtype wp.quatf and the WARN_ON_TORCH_QUATF_ACCESS environment variable is set to "1", each read emits a UserWarning pointing at the call site. This is a runtime aid for migrating Isaac Lab 2.x code (which used the (w, x, y, z) quaternion convention) to Isaac Lab 3.x's (x, y, z, w) convention.

property shape: tuple[int, ...][源代码]

Shape of the underlying warp array.

property dtype[源代码]

Warp dtype of the underlying array.

property device: str[源代码]

Device string of the underlying warp array.

目录