Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions docs/sphinx/source/changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,31 @@ PyPI 版本变更与未发布变更;发布日期采用 PyPI 上传日期。完

### Added / 新增

- Built-in reset-mode model-field DR terms now accept a ``ResetSelection``,
so tasks using them (for example G1 motion tracking with `foot_friction`)
can enable fixed-shape autoreset (`env.autoreset_cuda_graph`): the masked
path samples at full width and merges through the packed reset
transaction instead of the row-index staging. Covered terms: geom
friction, joint armature, PD gains, rigid-body CoM and encoder bias; the
value-validity check that the row-index path runs eagerly on the host is
published as a deferred device verdict on the masked path. New public
entity tensor-mask write gateways back the model-field terms:
`Entity.write_geom_friction_tensor_mask`,
`Entity.write_joint_armature_tensor_mask` and
`Entity.write_body_ipos_tensor_mask`
([#2623](https://github.com/Motphys/UniLab/issues/2623)).
内置 reset 模式 model-field DR term 现接受 ``ResetSelection``,使用这些
term 的任务(例如带 `foot_friction` 的 G1 motion tracking)可以开启
fixed-shape autoreset(`env.autoreset_cuda_graph`):掩码路径以全宽度采样,
并通过 packed reset 事务合并,取代行索引暂存。覆盖项:geom friction、
joint armature、PD gains、刚体质心与 encoder bias;行索引路径在 host 上
即时执行的值合法性检查在掩码路径上发布为推迟 device verdict。新增公共
entity 张量掩码写入口支撑这些 model-field term:
`Entity.write_geom_friction_tensor_mask`、
`Entity.write_joint_armature_tensor_mask` 与
`Entity.write_body_ipos_tensor_mask`
([#2623](https://github.com/Motphys/UniLab/issues/2623))。

- The documentation site is now versioned with sphinx-multiversion: the `main`
track plus the `x.y.0` release of every minor line (v1.0.0, v1.1.0, v1.2.0,
v1.3.0, v1.4.0, v1.5.0 at time of writing) are published with a
Expand Down Expand Up @@ -79,6 +104,16 @@ PyPI 版本变更与未发布变更;发布日期采用 PyPI 上传日期。完

### Changed / 变更

- `ResetStateTransaction` materializes the full-width device default table
for each reset randomization field only once and caches it per field
(invalidated when the packed reset device is redeclared), instead of
rebuilding it on every `write_randomization_tensor_mask` call
([#2623](https://github.com/Motphys/UniLab/issues/2623)).
`ResetStateTransaction` 现在对每个 reset 随机化字段只物化一次全宽度
device 默认表并按字段缓存(重声明 packed reset device 时失效),不再在
每次 `write_randomization_tensor_mask` 调用时重建
([#2623](https://github.com/Motphys/UniLab/issues/2623))。

- Collapse the fixed-shape autoreset switch chain into the single public
switch `env.autoreset_cuda_graph`: enabling it now implies masked autoreset,
persistent step buffers and deferred finite validation. The intermediate
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,15 @@ trajectories differ from the selected-row path. Compare the two modes
statistically, not value by value; MJWarp is not bitwise deterministic in any
case.

**Reset-mode DR replay cannot be disabled.** On backends that restore
model-field defaults at reset (such as MJWarp), the built-in reset-mode domain
randomization terms re-randomize through the packed reset transaction on every
step of the fixed-shape path. Skipping that replay is not supported: with
model-field writes restored to defaults, an un-replayed randomization would let
privileged observations and physics diverge from the first step. Running the
full reset lifecycle every step is the cost the fixed-shape path pays for its
sync-free, graph-capturable reset.

**`final_observation`.** It is published on every step and is meaningful only
on done rows.

Expand Down
93 changes: 93 additions & 0 deletions src/unilab/base/entity.py
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@
from unisim.dr.types import (
RESET_TERM_BODY_IPOS,
RESET_TERM_BODY_MASS,
RESET_TERM_DOF_ARMATURE,
RESET_TERM_GEOM_FRICTION,
RESET_TERM_KD,
RESET_TERM_KP,
Expand Down Expand Up @@ -3761,6 +3762,39 @@ def write_joint_armature_to_sim(
term_name=f"{term_name}:{self.name}",
)

def write_joint_armature_tensor_mask(
self,
reset_mask: torch.Tensor,
values: torch.Tensor,
joint_ids: torch.Tensor | Sequence[int] | slice | None = None,
*,
term_name: str = "joint_armature",
) -> None:
"""Stage full-width joint armatures selected by the transaction mask.

Fixed-shape counterpart of :meth:`write_joint_armature_to_sim` for the
``ResetSelection`` reset dispatch: ``values`` must be a contiguous
float32 tensor of shape ``(num_envs, selected_joints)`` on the packed
reset device; the transaction validates width, dtype, and device.
"""
if self._reset_state is None:
raise self._capability_error(
"reset joint-armature write",
"EntityScene was materialized without an env-owned reset transaction",
)
model_dof_ids = self._materialize_joint_model_dof_ids()
local_ids = self._normalize_local_joint_ids(
joint_ids,
capability="reset joint-armature write",
)
self._reset_state.write_randomization_tensor_mask(
RESET_TERM_DOF_ARMATURE,
reset_mask,
model_dof_ids[local_ids],
values,
term_name=f"{term_name}:{self.name}",
)

def bind_geom_friction_write(
self,
geom_ids: np.ndarray | Sequence[int] | slice | None = None,
Expand Down Expand Up @@ -3810,6 +3844,38 @@ def write_geom_friction_to_sim(
term_name=f"{term_name}:{self.name}",
)

def write_geom_friction_tensor_mask(
self,
reset_mask: torch.Tensor,
values: torch.Tensor,
geom_ids: torch.Tensor | Sequence[int] | slice | None = None,
*,
term_name: str = "geom_friction",
) -> None:
"""Stage full-width geom friction selected by the transaction mask.

Fixed-shape counterpart of :meth:`write_geom_friction_to_sim` for the
``ResetSelection`` reset dispatch: ``values`` must be a contiguous
float32 tensor of shape ``(num_envs, selected_geoms, 3)`` on the packed
reset device; the transaction validates width, dtype, and device.
"""
if self._reset_state is None or self._geom_ids is None:
raise self._capability_error(
"reset geom-friction write",
"geom metadata or the env-owned reset transaction was not materialized",
)
local_ids = self._normalize_local_geom_ids(
geom_ids,
capability="reset geom-friction write",
)
self._reset_state.write_randomization_tensor_mask(
RESET_TERM_GEOM_FRICTION,
reset_mask,
self._geom_ids[local_ids],
values,
term_name=f"{term_name}:{self.name}",
)

def bind_body_mass_write(
self,
body_ids: np.ndarray | Sequence[int] | slice | None = None,
Expand Down Expand Up @@ -3912,6 +3978,33 @@ def write_body_ipos_to_sim(
term_name=f"{term_name}:{self.name}",
)

def write_body_ipos_tensor_mask(
self,
reset_mask: torch.Tensor,
values: torch.Tensor,
body_ids: np.ndarray | Sequence[int] | slice | None = None,
*,
term_name: str = "randomize_rigid_body_com",
) -> None:
"""Stage full-width body inertial positions selected by the transaction mask.

Fixed-shape counterpart of :meth:`write_body_ipos_to_sim` for the
``ResetSelection`` reset dispatch: ``values`` must be a contiguous
float32 tensor of shape ``(num_envs, selected_bodies, 3)`` on the packed
reset device; the transaction validates width, dtype, and device.
"""
reset_state, _, backend_ids = self._bind_body_randomization(
body_ids,
capability="reset body-ipos write",
)
reset_state.write_randomization_tensor_mask(
RESET_TERM_BODY_IPOS,
reset_mask,
backend_ids,
values,
term_name=f"{term_name}:{self.name}",
)

def record_startup_body_ipos_to_sim(
self,
values: torch.Tensor,
Expand Down
26 changes: 22 additions & 4 deletions src/unilab/base/reset_state.py
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,11 @@ def __init__(
self._default_kp: np.ndarray | None = None
self._default_kd: np.ndarray | None = None
self._randomization_defaults: dict[str, np.ndarray] = {}
# Immutable full-width float32 default tables on the packed reset
# device, materialized once per field and reused by every
# ``write_randomization_tensor_mask`` call; cleared when the packed
# reset device is (re)declared.
self._tensor_randomization_defaults: dict[str, torch.Tensor] = {}
self._startup_randomization_fields: set[str] = set()
self._requesting_terms: set[str] = set()
self._last_commit_had_writes = False
Expand Down Expand Up @@ -288,6 +293,9 @@ def declare_packed_reset_device(self, device: torch.device) -> None:
"PackedResetTransaction", bind_packed_reset(device=resolved)
)
self._packed_reset_transaction.validation = self._packed_validation_mode
# The packed composer and its device tables are rebuilt: per-field
# tensor defaults cached for the previous declaration are stale.
self._tensor_randomization_defaults.clear()
self._packed_state_default_installed = False

@contextmanager
Expand Down Expand Up @@ -1119,7 +1127,16 @@ def write_randomization_tensor_mask(
self._tensor_has_writes = True

def _materialize_tensor_randomization_default(self, field: str, term_name: str) -> torch.Tensor:
"""Build the immutable per-env device base for one DR field on the cold path."""
"""Return the immutable per-env device base for one DR field.

The full-width float32 table is materialized once per field and cached:
``write_randomization_tensor_mask`` only reads ``shape[1]`` (the column
width) from it, so the cached tensor is never mutated. The cache is
cleared when the packed reset device is (re)declared.
"""
cached = self._tensor_randomization_defaults.get(field)
if cached is not None:
return cached
device = self._packed_reset_device
if device is None:
raise RuntimeError("device tensor reset requires its selected device to be declared")
Expand All @@ -1133,9 +1150,10 @@ def _materialize_tensor_randomization_default(self, field: str, term_name: str)
default = self._require_randomization_default(field, term_name)
assert default is not None
table = torch.as_tensor(np.array(default, dtype=np.float32, copy=True), device=device)
if self._default_is_per_env(default, field=field):
return table
return table.unsqueeze(0).expand(self._num_envs, *table.shape).contiguous()
if not self._default_is_per_env(default, field=field):
table = table.unsqueeze(0).expand(self._num_envs, *table.shape).contiguous()
self._tensor_randomization_defaults[field] = table
return table

def reset_to_default(self, reset_mask: torch.Tensor, *, term_name: str) -> None:
"""Stage backend default qpos/qvel for the active full-width mask."""
Expand Down
Loading
Loading