From 5446d703bb1d3be278258e272fdac7e85758645b Mon Sep 17 00:00:00 2001 From: TATP-233 Date: Thu, 19 Nov 2026 23:12:03 +0800 Subject: [PATCH] feat(reset): support ResetSelection in built-in model-field DR terms (#2623) Fixed-shape autoreset (env.autoreset_cuda_graph) negotiates ResetSelection support with every reset-mode event term; the built-in model-field DR terms (geom friction, joint armature, PD gains, rigid-body CoM, encoder bias) previously had no declaration and blocked tasks such as G1 motion tracking. Masked path: sample at full width from device-staged immutable tables (sampling ranges, field defaults, gain defaults, CoM ranges, joint columns), merge through the packed reset transaction via the new entity tensor-mask gateways, and publish value validity through the env's deferred verdict channel (env.require) instead of the eager host check. Sampling tables are staged once on the cold path so captured resets stay sync-free. ResetStateTransaction now caches the per-field full-width device default table used by write_randomization_tensor_mask, clearing the cache when the packed reset device is redeclared. Remaining reset DR terms (randomize_rigid_body_mass, randomize_body_mass_inertia, randomize_physics_scene_gravity) are follow-ups. --- docs/sphinx/source/changelog.md | 35 +++ .../1-training/8-sync_free_autoreset.md | 9 + src/unilab/base/entity.py | 93 +++++++ src/unilab/base/reset_state.py | 26 +- src/unilab/envs/mdp/events.py | 257 ++++++++++++++++-- tests/base/test_reset_state.py | 140 ++++++++++ tests/envs/mdp/test_events.py | 182 +++++++++++++ 7 files changed, 722 insertions(+), 20 deletions(-) diff --git a/docs/sphinx/source/changelog.md b/docs/sphinx/source/changelog.md index 152c9a3c3..9dd56b003 100644 --- a/docs/sphinx/source/changelog.md +++ b/docs/sphinx/source/changelog.md @@ -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 @@ -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 diff --git a/docs/sphinx/source/en/2-user_guide/1-training/8-sync_free_autoreset.md b/docs/sphinx/source/en/2-user_guide/1-training/8-sync_free_autoreset.md index 77ad993ad..fc28b4b95 100644 --- a/docs/sphinx/source/en/2-user_guide/1-training/8-sync_free_autoreset.md +++ b/docs/sphinx/source/en/2-user_guide/1-training/8-sync_free_autoreset.md @@ -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. diff --git a/src/unilab/base/entity.py b/src/unilab/base/entity.py index 95eeab7b3..f53b93c8b 100644 --- a/src/unilab/base/entity.py +++ b/src/unilab/base/entity.py @@ -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, @@ -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, @@ -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, @@ -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, diff --git a/src/unilab/base/reset_state.py b/src/unilab/base/reset_state.py index 498b9ad24..b8bdd7842 100644 --- a/src/unilab/base/reset_state.py +++ b/src/unilab/base/reset_state.py @@ -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 @@ -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 @@ -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") @@ -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.""" diff --git a/src/unilab/envs/mdp/events.py b/src/unilab/envs/mdp/events.py index 240eba9b5..81dfe2f9a 100644 --- a/src/unilab/envs/mdp/events.py +++ b/src/unilab/envs/mdp/events.py @@ -15,6 +15,7 @@ import torch +from unilab.base.reset_selection import ResetSelection from unilab.base.reset_selectors import ResetMaskBuffer from unilab.managers.event_manager import EventTermCfg from unilab.managers.manager_base import ManagerTermBase @@ -407,6 +408,9 @@ class _ModelFieldRandomizer(_ResetRandomizationTerm): _PARAMS = frozenset( ("ranges", "asset_cfg", "distribution", "operation", "axes", "shared_random") ) + # Both the row-index and the ResetSelection ``__call__`` paths are + # implemented on this base, so subclasses inherit the declaration. + supports_reset_selection = True def __init__(self, cfg: EventTermCfg, env: ManagerBasedRlEnv): super().__init__(env) @@ -456,6 +460,7 @@ def __init__(self, cfg: EventTermCfg, env: ManagerBasedRlEnv): self._axes = self._resolve_axes(cfg.params.get("axes"), ranges) self._ranges = self._resolve_ranges(ranges, names) self._device_ranges: torch.Tensor | None = None + self._device_defaults: torch.Tensor | None = None self._device_axis_groups: dict[ int, list[tuple[torch.Tensor, torch.Tensor, torch.Tensor]] ] = {} @@ -474,6 +479,14 @@ def _write( ) -> None: raise NotImplementedError + def _write_mask( + self, + values: torch.Tensor, + reset_mask: torch.Tensor, + ) -> None: + """Stage full-width values for the rows selected by ``reset_mask``.""" + raise NotImplementedError + def _select_string_ranges( self, local_ids: torch.Tensor, @@ -647,31 +660,98 @@ def _sample_axis_on_device(self, rng: ManagerRng, axis: int, count: int) -> torc groups = self._build_axis_groups(axis) self._device_axis_groups[axis] = groups samples = torch.empty( - (count, parameters.shape[0]), dtype=torch.float32, device=parameters.device + (count, parameters.shape[0]), dtype=parameters.dtype, device=parameters.device ) for low, high, indices in groups: shared = _sample_distribution_on_device(rng, low, high, (count, 1), self._distribution) - samples[:, indices] = shared + samples[:, indices] = shared.to(dtype=samples.dtype) return samples def _sample_device(self, env: ManagerBasedRlEnv) -> torch.device: return _require_rng(env, self.name).device def _sample_axis(self, env: ManagerBasedRlEnv, axis: int, count: int) -> torch.Tensor: - parameters = self._ranges[:, axis].to(device=self._sample_device(env)) rng = _require_rng(env, self.name) - return _sample_axis_on_device( - rng, - parameters, - count, - distribution=self._distribution, - shared_random=self._shared_random, + device = self._sample_device(env) + ranges = self._device_ranges + if ranges is None or ranges.device != device: + # Cold path: stage the immutable sampling table on the RNG device + # once. Reset replays — including captured fixed-shape autoresets — + # then sample without any host transfer or host-read grouping. + ranges = self._ranges.to(device=device) + self._device_ranges = ranges + self._device_axis_groups.clear() + return self._sample_axis_on_device(rng, axis, count) + + def _full_default_rows(self, env: ManagerBasedRlEnv) -> torch.Tensor: + """Full-width default table on the sampling device (cold-path staged once).""" + device = self._sample_device(env) + table = self._device_defaults + if table is None or table.device != device: + table = self._defaults.to(device=device) + self._device_defaults = table + canonical_ndim = 1 if self._field_width == 1 else 2 + if table.ndim == canonical_ndim: + return table.unsqueeze(0).expand(self.num_envs, *table.shape) + if table.ndim == canonical_ndim + 1: + return table + raise ValueError( + f"EventManager term '{self._term_name}' bound an invalid default table with " + f"shape {tuple(table.shape)}" + ) + + def _apply_selection(self, env: ManagerBasedRlEnv, selection: ResetSelection) -> None: + """Fixed-width masked randomization for the ``ResetSelection`` dispatch. + + Sampling runs at full width with a fixed shape, so a device-resident or + captured reset replays without host reads. Value validity that the + row-index path checks eagerly on the host is published through + ``env.require`` as a deferred device verdict instead; the write merges + into the active device reset transaction through the field's + tensor-mask gateway. + """ + if not self._entity.reset_state_tensor_active: + raise RuntimeError( + f"EventManager term '{self._term_name}' masked randomization requires an " + "active device reset transaction" + ) + count = selection.num_envs + default_values = self._full_default_rows(env) + sampled_axis = self._sample_axis(env, self._axes[0], count) if self._axes else None + values = default_values.clone() + for index, axis in enumerate(self._axes): + samples = sampled_axis if index == 0 else self._sample_axis(env, axis, count) + if self._field_width == 1: + values = _apply_randomization_operation( + default_values, + samples, + self._operation, + ) + else: + values[..., axis] = _apply_randomization_operation( + default_values[..., axis], + samples, + self._operation, + ) + values = values.to(device=selection.mask.device, dtype=torch.float32).contiguous() + valid = torch.isfinite(values).all() & (values >= 0.0).all() + require = getattr(env, "require", None) + if not callable(require): + raise RuntimeError( + f"EventManager term '{self._term_name}' ResetSelection path requires " + "deferred finite validation (env.finite_validation_mode='deferred')" + ) + require( + valid, + f"event.{self._term_name}", + f"EventManager term '{self._term_name}' produced negative, NaN, or Inf values", ) + self._write_mask(values, selection.mask) def __call__( self, env: ManagerBasedRlEnv, - env_ids: torch.Tensor | None, + env_ids: torch.Tensor | ResetSelection | None, ranges: Any, asset_cfg: SceneEntityCfg = _DEFAULT_ASSET_CFG, distribution: str = "uniform", @@ -680,6 +760,9 @@ def __call__( shared_random: bool = False, ) -> None: del ranges, asset_cfg, distribution, operation, axes, shared_random + if isinstance(env_ids, ResetSelection): + self._apply_selection(env, env_ids) + return ids = resolve_env_ids(env, env_ids) default_values = _model_field_default_rows( self._defaults, @@ -742,6 +825,14 @@ def _write(self, values: torch.Tensor, env_ids: torch.Tensor) -> None: term_name=self._term_name, ) + def _write_mask(self, values: torch.Tensor, reset_mask: torch.Tensor) -> None: + self._entity.write_geom_friction_tensor_mask( + reset_mask, + values, + self._local_ids, + term_name=self._term_name, + ) + class DofArmature(_ModelFieldRandomizer): """Pinned mjlab-style dof armature randomization through the reset payload.""" @@ -768,6 +859,14 @@ def _write(self, values: torch.Tensor, env_ids: torch.Tensor) -> None: term_name=self._term_name, ) + def _write_mask(self, values: torch.Tensor, reset_mask: torch.Tensor) -> None: + self._entity.write_joint_armature_tensor_mask( + reset_mask, + values, + self._local_ids, + term_name=self._term_name, + ) + geom_friction = GeomFriction dof_armature = DofArmature @@ -830,11 +929,53 @@ def __init__(self, cfg: EventTermCfg, env: ManagerBasedRlEnv): term_name="pd_gains", ) ) + self._device_default_kp_or_kd: tuple[torch.Tensor, torch.Tensor] | None = None + + supports_reset_selection = True + + def _device_gain_defaults(self, device: torch.device) -> tuple[torch.Tensor, torch.Tensor]: + """Immutable gain default tables staged on the sampling device once.""" + cached = self._device_default_kp_or_kd + if cached is not None and cached[0].device == device: + return cached + staged = (self._default_kp.to(device=device), self._default_kd.to(device=device)) + self._device_default_kp_or_kd = staged + return staged + + def _apply_selection(self, env: ManagerBasedRlEnv, selection: ResetSelection) -> None: + """Fixed-width masked gain randomization for the ``ResetSelection`` dispatch.""" + if not self._entity.reset_state_tensor_active: + raise RuntimeError( + "EventManager term 'pd_gains' masked randomization requires an active " + "device reset transaction" + ) + rng = _require_rng(env, "pd_gains") + count = selection.num_envs + shape = (count, len(self._actuator_ids)) + kp = _sample_gain_range(rng, self._kp_range, shape, self._distribution) + kd = _sample_gain_range(rng, self._kd_range, shape, self._distribution) + if self._operation == "scale": + default_kp, default_kd = self._device_gain_defaults(kp.device) + if default_kp.ndim == 1: + default_kp = default_kp.unsqueeze(0).expand(count, *default_kp.shape) + if default_kd.ndim == 1: + default_kd = default_kd.unsqueeze(0).expand(count, *default_kd.shape) + kp = kp * default_kp.to(dtype=kp.dtype, device=kp.device) + kd = kd * default_kd.to(dtype=kd.dtype, device=kd.device) + kp = kp.to(device=selection.mask.device, dtype=torch.float32).contiguous() + kd = kd.to(device=selection.mask.device, dtype=torch.float32).contiguous() + self._entity.write_actuator_gains_tensor_mask( + selection.mask, + kp, + kd, + actuator_ids=self._actuator_ids, + term_name="pd_gains", + ) def __call__( self, env: ManagerBasedRlEnv, - env_ids: torch.Tensor | None, + env_ids: torch.Tensor | ResetSelection | None, kp_range: tuple[float, float], kd_range: tuple[float, float], asset_cfg: SceneEntityCfg = _DEFAULT_ASSET_CFG, @@ -842,6 +983,9 @@ def __call__( operation: Literal["scale", "abs"] = "scale", ) -> None: del kp_range, kd_range, asset_cfg, distribution, operation + if isinstance(env_ids, ResetSelection): + self._apply_selection(env, env_ids) + return ids = resolve_env_ids(env, env_ids) shape = (ids.numel(), len(self._actuator_ids)) kp = _sample_gain_range( @@ -1203,6 +1347,63 @@ def __init__(self, cfg: EventTermCfg, env: ManagerBasedRlEnv): ) self._startup = cfg.mode == "startup" self._startup_values: torch.Tensor | None = None + self._device_default_ipos: torch.Tensor | None = None + self._device_com_ranges: tuple[tuple[tuple[float, float], ...], torch.Tensor] | None = None + + supports_reset_selection = True + + def _apply_selection( + self, + env: ManagerBasedRlEnv, + selection: ResetSelection, + com_range: dict[str, tuple[float, float]], + ) -> None: + """Fixed-width masked CoM randomization for the ``ResetSelection`` dispatch. + + The live ``com_range`` is still re-resolved from the term params on + every apply (curricula may stage it); only the resolved bounds are + staged on the sampling device, and only when they change. + """ + if not self._entity.reset_state_tensor_active: + raise RuntimeError( + "EventManager term 'randomize_rigid_body_com' masked randomization " + "requires an active device reset transaction" + ) + rng = _require_rng(env, "randomize_rigid_body_com") + ranges = _axis_ranges( + com_range, + term_name="randomize_rigid_body_com", + name="com_range", + keys=_XYZ_KEYS, + ) + key = tuple((float(lower), float(upper)) for lower, upper in ranges.detach().cpu().tolist()) + cached = self._device_com_ranges + if cached is None or cached[0] != key or cached[1].device != rng.device: + device_ranges = ranges.to(device=rng.device) + self._device_com_ranges = (key, device_ranges) + else: + device_ranges = cached[1] + count = selection.num_envs + offsets = rng.uniform( + device_ranges[:, 0], + device_ranges[:, 1], + (count, 3), + dtype=torch.float64, + ) + defaults = self._device_default_ipos + if defaults is None or defaults.device != offsets.device: + defaults = self._default_ipos.to(device=offsets.device) + self._device_default_ipos = defaults + if defaults.ndim == 2: + defaults = defaults.unsqueeze(0).expand(count, *defaults.shape) + values = defaults + offsets[:, None, :] + values = values.to(device=selection.mask.device, dtype=torch.float32).contiguous() + self._entity.write_body_ipos_tensor_mask( + selection.mask, + values, + body_ids=self._body_ids, + term_name="randomize_rigid_body_com", + ) def _apply_startup( self, @@ -1253,7 +1454,7 @@ def _apply_startup( def __call__( self, env: ManagerBasedRlEnv, - env_ids: torch.Tensor | None, + env_ids: torch.Tensor | ResetSelection | None, com_range: dict[str, tuple[float, float]], asset_cfg: SceneEntityCfg, ) -> None: @@ -1261,6 +1462,9 @@ def __call__( if self._startup: self._apply_startup(env, env_ids, com_range) return + if isinstance(env_ids, ResetSelection): + self._apply_selection(env, env_ids, com_range) + return ranges = _axis_ranges( com_range, term_name="randomize_rigid_body_com", @@ -1832,23 +2036,37 @@ def __init__(self, cfg: EventTermCfg, env: ManagerBasedRlEnv): f"EventManager term '{term_name}' asset_cfg must select at least one joint" ) self._joint_ids = joint_ids + self._columns: torch.Tensor | None = None self._reset_mask_buffer = ResetMaskBuffer(self.num_envs, torch.device(env.device)) + supports_reset_selection = True + + def _joint_columns(self, device: torch.device) -> torch.Tensor: + """Selected joint columns staged on the control device once (cold path). + + Building the index tensor inside the reset call would copy from pageable + host memory on every reset, which CUDA graph capture rejects. + """ + cached = self._columns + if cached is None or cached.device != device: + cached = torch.tensor(self._joint_ids, dtype=torch.int64, device=device) + self._columns = cached + return cached + def __call__( self, env: ManagerBasedRlEnv, - env_ids: torch.Tensor | None, + env_ids: torch.Tensor | ResetSelection | None, bias_range: tuple[float, float], asset_cfg: SceneEntityCfg, ) -> None: del bias_range, asset_cfg control = getattr(self._entity.data, "control_buffer", None) if isinstance(control, torch.Tensor): - columns = torch.tensor(self._joint_ids, dtype=torch.int64, device=control.device) + columns = self._joint_columns(control.device) rng_owner = getattr(env, "rng", None) if rng_owner is None: raise NotImplementedError("Tensor encoder-bias reset requires the Manager RNG") - ids = resolve_env_ids(env, env_ids) lower, upper = self._range sampled = rng_owner.uniform( lower, @@ -1856,7 +2074,14 @@ def __call__( (self.num_envs, columns.numel()), dtype=torch.float32, ) - reset_mask = self._reset_mask_buffer.scatter(ids) + # Sampling is full-width with a fixed shape already; only the mask + # derivation differs between row indices and a ResetSelection. + if env_ids is None: + raise ValueError( + "EventManager term 'randomize_encoder_bias' requires concrete " + "environment indices" + ) + reset_mask = self._reset_mask_buffer.scatter(env_ids) self._entity.data.update_encoder_bias_tensor_mask(reset_mask, columns, sampled) return raise NotImplementedError( diff --git a/tests/base/test_reset_state.py b/tests/base/test_reset_state.py index dc833c400..a7f4ec538 100644 --- a/tests/base/test_reset_state.py +++ b/tests/base/test_reset_state.py @@ -1110,6 +1110,146 @@ def test_packed_transaction_owns_dr_merge_and_baselines() -> None: ) +class _CountingPackedBackend(_PackedTensorResetBackend): + """Packed fake counting per-term default fetches.""" + + def __init__(self) -> None: + super().__init__() + self.default_term_calls: dict[str, int] = {} + + def get_reset_term_default(self, term: str) -> np.ndarray: + self.default_term_calls[term] = self.default_term_calls.get(term, 0) + 1 + return super().get_reset_term_default(term) + + +def _count_tensor_default_materializations(monkeypatch: pytest.MonkeyPatch) -> list[str]: + """Record every ``_materialize_tensor_randomization_default`` field argument.""" + materialized: list[str] = [] + original = ResetStateTransaction._materialize_tensor_randomization_default + + def counting(self: ResetStateTransaction, field: str, term_name: str) -> torch.Tensor: + if field not in self._tensor_randomization_defaults: + materialized.append(field) + return original(self, field, term_name) + + monkeypatch.setattr( + ResetStateTransaction, "_materialize_tensor_randomization_default", counting + ) + return materialized + + +def test_tensor_randomization_defaults_materialize_once_per_field( + monkeypatch: pytest.MonkeyPatch, +) -> None: + backend = _CountingPackedBackend() + transaction = _transaction(backend) + transaction.declare_packed_reset_device(torch.device("cpu")) + _bind_device_mass(transaction) + materialized = _count_tensor_default_materializations(monkeypatch) + + first_mask = torch.tensor([True, True, False, False]) + with transaction.scoped_device_event_tensor(first_mask): + transaction.write_randomization_tensor_mask( + RESET_TERM_BODY_MASS, + first_mask, + np.array([0], dtype=np.int32), + torch.tensor([[7.0], [8.0], [0.0], [0.0]]), + term_name="first_reset_mass", + ) + second_mask = torch.tensor([False, True, True, False]) + with transaction.scoped_device_event_tensor(second_mask): + transaction.write_randomization_tensor_mask( + RESET_TERM_BODY_MASS, + second_mask, + np.array([1], dtype=np.int32), + torch.tensor([[0.0], [9.0], [10.0], [0.0]]), + term_name="second_reset_mass", + ) + + assert materialized == [RESET_TERM_BODY_MASS] + randomization = backend.tensor_reset_calls[-1][3] + assert isinstance(randomization, TensorResetRandomizationPayload) + torch.testing.assert_close( + randomization.body_mass, + torch.tensor([[8.0, 9.0], [2.0, 10.0]]), + ) + + +def test_actuator_gain_tensor_defaults_materialize_once_across_transactions( + monkeypatch: pytest.MonkeyPatch, +) -> None: + backend = _CountingPackedBackend() + transaction = _transaction(backend) + transaction.declare_packed_reset_device(torch.device("cpu")) + materialized = _count_tensor_default_materializations(monkeypatch) + + first_mask = torch.tensor([True, False, False, False]) + with transaction.scoped_device_event_tensor(first_mask): + transaction.write_randomization_tensor_mask( + RESET_TERM_KP, + first_mask, + np.array([0], dtype=np.int32), + torch.tensor([[7.0], [0.0], [0.0], [0.0]]), + term_name="first_reset_kp", + ) + transaction.write_randomization_tensor_mask( + RESET_TERM_KD, + first_mask, + np.array([1], dtype=np.int32), + torch.tensor([[0.0], [0.0], [0.0], [0.0]]), + term_name="first_reset_kd", + ) + second_mask = torch.tensor([False, True, False, False]) + with transaction.scoped_device_event_tensor(second_mask): + transaction.write_randomization_tensor_mask( + RESET_TERM_KP, + second_mask, + np.array([0], dtype=np.int32), + torch.tensor([[0.0], [8.0], [0.0], [0.0]]), + term_name="second_reset_kp", + ) + + assert materialized == [RESET_TERM_KP, RESET_TERM_KD] + randomization = backend.tensor_reset_calls[-1][3] + assert isinstance(randomization, TensorResetRandomizationPayload) + torch.testing.assert_close(randomization.kp[:, 0], torch.tensor([8.0])) + + +def test_redeclaring_packed_reset_device_clears_tensor_default_cache( + monkeypatch: pytest.MonkeyPatch, +) -> None: + backend = _CountingPackedBackend() + transaction = _transaction(backend) + transaction.declare_packed_reset_device(torch.device("cpu")) + _bind_device_mass(transaction) + materialized = _count_tensor_default_materializations(monkeypatch) + + def write_masked() -> None: + mask = torch.tensor([True, False, False, False]) + with transaction.scoped_device_event_tensor(mask): + transaction.write_randomization_tensor_mask( + RESET_TERM_BODY_MASS, + mask, + np.array([0], dtype=np.int32), + torch.tensor([[7.0], [0.0], [0.0], [0.0]]), + term_name="reset_mass", + ) + + write_masked() + assert materialized == [RESET_TERM_BODY_MASS] + # The same device short-circuits and keeps the cache. + transaction.declare_packed_reset_device(torch.device("cpu")) + write_masked() + assert materialized == [RESET_TERM_BODY_MASS] + # A changed declaration rebuilds the packed composer and invalidates the + # cache. Torch collapses ``cpu:0`` to ``cpu`` at tensor creation, so nudge + # the stored device directly to simulate the rebuild trigger. + transaction._packed_reset_device = torch.device("cpu", 0) + transaction.declare_packed_reset_device(torch.device("cpu")) + write_masked() + assert materialized == [RESET_TERM_BODY_MASS, RESET_TERM_BODY_MASS] + + def test_host_commit_promotes_public_packed_reset_baseline() -> None: backend = _PackedTensorResetBackend() transaction = _transaction(backend) diff --git a/tests/envs/mdp/test_events.py b/tests/envs/mdp/test_events.py index 093b8c672..eb7a6aedd 100644 --- a/tests/envs/mdp/test_events.py +++ b/tests/envs/mdp/test_events.py @@ -38,6 +38,7 @@ ) from unilab.base.entity import EntityCfg, EntityScene, SceneTensorReadSpec +from unilab.base.reset_selection import ResetSelection from unilab.base.reset_selectors import ResetMaskBuffer from unilab.base.reset_state import ResetStateTransaction from unilab.envs import mdp @@ -824,6 +825,159 @@ def test_pd_gains_commits_masked_packed_model_fields() -> None: np.testing.assert_allclose(payload.kd.numpy(), [[3.0] * 3, [3.0] * 3]) +def _selection_env( + **kwargs: Any, +) -> tuple[ManagerBasedRlEnv, _Backend, ResetStateTransaction, list[torch.Tensor]]: + """Transaction env extended with the fixed-shape reset dispatch surface. + + ``require`` records the deferred verdicts so tests can assert the masked + path published its validity check without a host read during the scope. + """ + env, backend, transaction = _transaction_env(**kwargs) + verdicts: list[torch.Tensor] = [] + + def require(ok: torch.Tensor, name: str, message: str) -> None: + del name, message + verdicts.append(ok) + + namespace = SimpleNamespace( + step_counter_tensor=torch.zeros((), dtype=torch.int64), + require=require, + **vars(env), + ) + return cast(ManagerBasedRlEnv, namespace), backend, transaction, verdicts + + +def _selection(mask_values: list[bool]) -> ResetSelection: + mask = torch.tensor(mask_values, dtype=torch.bool) + return ResetSelection(mask=mask, row_ids=torch.arange(mask.numel(), dtype=torch.int64)) + + +def test_geom_friction_reset_selection_commits_masked_packed_model_fields() -> None: + env, backend, transaction, verdicts = _selection_env() + manager = EventManager( + { + "friction": EventTermCfg( + func=mdp.geom_friction, + mode="reset", + params={"ranges": (2.0, 2.0), "operation": "scale"}, + ) + }, + env, + ) + assert manager.reset_selection_blockers() == [] + transaction.declare_packed_reset_device(torch.device("cpu")) + selection = _selection([False, True, True]) + + with transaction.scoped_device_event_tensor(selection.mask): + manager.apply("reset", env_ids=selection, global_env_step_count=0) + assert backend.set_state_calls == [] + + assert len(backend.set_state_calls) == 1 + rows, _qpos, _qvel = backend.set_state_calls[0] + np.testing.assert_array_equal(rows, [1, 2]) + payload = backend.randomization_calls[0] + assert payload is not None + # Default axes randomize only the first friction component, matching the + # row-index path of the same term. + expected = np.asarray([[1.0, 0.01, 0.001], [1.4, 0.02, 0.002], [1.8, 0.03, 0.003]]) + np.testing.assert_allclose(payload.geom_friction.numpy(), np.broadcast_to(expected, (2, 3, 3))) + assert verdicts and all(bool(verdict) for verdict in verdicts) + + +def test_dof_armature_reset_selection_commits_masked_packed_model_fields() -> None: + env, backend, transaction, verdicts = _selection_env() + manager = EventManager( + { + "armature": EventTermCfg( + func=mdp.dof_armature, + mode="reset", + params={"ranges": (2.0, 2.0), "operation": "scale"}, + ) + }, + env, + ) + assert manager.reset_selection_blockers() == [] + transaction.declare_packed_reset_device(torch.device("cpu")) + selection = _selection([True, False, True]) + + with transaction.scoped_device_event_tensor(selection.mask): + manager.apply("reset", env_ids=selection, global_env_step_count=0) + assert backend.set_state_calls == [] + + assert len(backend.set_state_calls) == 1 + rows, _qpos, _qvel = backend.set_state_calls[0] + np.testing.assert_array_equal(rows, [0, 2]) + payload = backend.randomization_calls[0] + assert payload is not None + np.testing.assert_allclose(payload.dof_armature.numpy(), [[0.0] * 6 + [2.0, 4.0, 6.0]] * 2) + assert verdicts and all(bool(verdict) for verdict in verdicts) + + +def test_pd_gains_reset_selection_commits_masked_packed_model_fields() -> None: + env, backend, transaction, _verdicts = _selection_env() + manager = EventManager( + { + "gain": EventTermCfg( + func=mdp.pd_gains, + mode="reset", + params={ + "kp_range": (2.0, 2.0), + "kd_range": (3.0, 3.0), + "operation": "abs", + }, + ) + }, + env, + ) + assert manager.reset_selection_blockers() == [] + transaction.declare_packed_reset_device(torch.device("cpu")) + selection = _selection([True, False, True]) + + with transaction.scoped_device_event_tensor(selection.mask): + manager.apply("reset", env_ids=selection, global_env_step_count=0) + assert backend.set_state_calls == [] + + assert len(backend.set_state_calls) == 1 + rows, _qpos, _qvel = backend.set_state_calls[0] + np.testing.assert_array_equal(rows, [0, 2]) + payload = backend.randomization_calls[0] + assert payload is not None + np.testing.assert_allclose(payload.kp.numpy(), [[2.0] * 3, [2.0] * 3]) + np.testing.assert_allclose(payload.kd.numpy(), [[3.0] * 3, [3.0] * 3]) + + +def test_body_com_reset_selection_commits_masked_packed_model_fields() -> None: + env, backend, transaction, _verdicts = _selection_env() + manager = EventManager( + { + "com": EventTermCfg( + func=mdp.randomize_rigid_body_com, + mode="reset", + params={ + "asset_cfg": SceneEntityCfg("robot", body_names=("base",)), + "com_range": {"x": (0.1, 0.1)}, + }, + ) + }, + env, + ) + assert manager.reset_selection_blockers() == [] + transaction.declare_packed_reset_device(torch.device("cpu")) + selection = _selection([False, True, True]) + + with transaction.scoped_device_event_tensor(selection.mask): + manager.apply("reset", env_ids=selection, global_env_step_count=0) + assert backend.set_state_calls == [] + + assert len(backend.set_state_calls) == 1 + rows, _qpos, _qvel = backend.set_state_calls[0] + np.testing.assert_array_equal(rows, [1, 2]) + payload = backend.randomization_calls[0] + assert payload is not None + np.testing.assert_allclose(payload.body_ipos.numpy(), [[[0.1, 0.0, 0.0]]] * 2) + + def test_model_field_capability_gaps_fail_cold() -> None: env, backend, _ = _transaction_env(randomization_supported=False) @@ -1509,6 +1663,34 @@ def test_randomize_encoder_bias_samples_selected_joints_within_range() -> None: assert np.any(bias[[0, 2]][:, [1, 3]] != 0.0) +def test_randomize_encoder_bias_reset_selection_samples_selected_rows() -> None: + env = _bias_env() + env.step_counter_tensor = torch.zeros((), dtype=torch.int64) + manager = EventManager( + { + "bias": EventTermCfg( + func=mdp.randomize_encoder_bias, + mode="reset", + params={ + "bias_range": (-0.02, 0.02), + "asset_cfg": SceneEntityCfg("robot", joint_ids=[1, 3]), + }, + ) + }, + env, + ) + assert manager.reset_selection_blockers() == [] + + manager.apply("reset", env_ids=_selection([True, False, True]), global_env_step_count=0) + + bias = env.scene["robot"].data.encoder_bias + assert bias.shape == (3, 4) + np.testing.assert_array_equal(bias[1], np.zeros(4)) + np.testing.assert_array_equal(bias[:, [0, 2]], np.zeros((3, 2))) + assert np.all(np.abs(bias[[0, 2]][:, [1, 3]]) <= 0.02) + assert np.any(bias[[0, 2]][:, [1, 3]] != 0.0) + + def test_randomize_encoder_bias_fails_closed_without_torch_control_plane() -> None: env = _bias_env(tensor_control=False) manager = EventManager(