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(