Skip to content
Open
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
Original file line number Diff line number Diff line change
Expand Up @@ -226,8 +226,11 @@ superseded ADR-0006 may remain.

## Evidence In Repo

- Reusable tensor components: `src/unilab/tasks/motion_tracking/common/tensor_runtime.py`,
`src/unilab/tasks/motion_tracking/common/tensor_state_store.py`
- The reusable tensor component helpers once cited here
(`src/unilab/tasks/motion_tracking/common/tensor_runtime.py`,
`src/unilab/tasks/motion_tracking/common/tensor_state_store.py`) had no
production consumer once the Manager runtime became device-native; they
were removed in the YAGNI sweep for issue #2629.
- General Manager runtime to migrate: `src/unilab/envs/manager_based_rl_env.py`
- Legacy runtime: removed. The historical path
`src/unilab/base/np_env.py` no longer exists and is intentionally not cited
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -218,8 +218,10 @@ useful for launcher/debug/MPS isolation.
## Evidence In Repo

- Manager runtime: `src/unilab/envs/manager_based_rl_env.py`
- Tensor state store/readiness consumer:
`src/unilab/tasks/motion_tracking/common/tensor_state_store.py`
- The tensor state store once cited here
(`src/unilab/tasks/motion_tracking/common/tensor_state_store.py`) had no
production consumer once the Manager runtime became device-native; it was
removed in the YAGNI sweep for issue #2629.
- Public backend contract: `unisim.backend.base.SimBackend`
- Current tensor Manager backend scope:
`src/unilab/base/registry.py` (`_SUPPORTED_SIM_BACKENDS`,
Expand Down
5 changes: 2 additions & 3 deletions docs/sphinx/source/api_reference/logging/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,5 @@

The W&B / TensorBoard bridges and structured training loggers live in the
`unilab` distribution under `unilab.rl.logging` (the former `uni_rl.logging`
is merged into this repository; issue #2372): `OnPolicyLogger`,
`OffPolicyLogger`, the metric and runtime-manifest schemas, and the
trace-event recorder.
is merged into this repository; issue #2372): `OffPolicyLogger`,
the metric and runtime-manifest schemas, and the trace-event recorder.
92 changes: 92 additions & 0 deletions docs/sphinx/source/changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -207,6 +207,22 @@ PyPI 版本变更与未发布变更;发布日期采用 PyPI 上传日期。完
的模式相矛盾。该方法现在免同步;调用方需自行保证概率有限、非负且和为正,
方法 docstring 已注明
([#2624](https://github.com/Motphys/UniLab/issues/2624))。
- The crawl-slope WBT example in the motion-tracking task guide no longer
recommends `sampling_mode=start`, which the tensor sampler has never
supported (it raises `NotImplementedError` at env construction). The example
now uses `sampling_mode=mixed` with `sampling_start_ratio=1.0`, the
supported deterministic clip-start form, in both the English and Chinese
pages; `MotionCommandCfg.sampling_mode` is narrowed to
`Literal["adaptive", "mixed"]` so invalid values are rejected by config
validation with a clear error instead of failing deep inside the tensor
sampler ([#2629](https://github.com/Motphys/UniLab/issues/2629)).
motion-tracking 任务指南中的 crawl-slope WBT 示例不再推荐
`sampling_mode=start`(tensor sampler 从未支持该值,会在 env 构造期抛
`NotImplementedError`)。示例改用受支持的确定性 clip 起点形式
`sampling_mode=mixed` 加 `sampling_start_ratio=1.0`,中英文页面同步修正;
`MotionCommandCfg.sampling_mode` 收窄为 `Literal["adaptive", "mixed"]`,
非法值在配置校验处即被清晰拒绝,不再深入 tensor sampler 才失败
([#2629](https://github.com/Motphys/UniLab/issues/2629))。

### Removed / 移除

Expand All @@ -225,6 +241,82 @@ PyPI 版本变更与未发布变更;发布日期采用 PyPI 上传日期。完
或用 `None` 表示全部行。保留形式为 `None`、一维整数行索引张量与内部
`ResetSelection` 协议;不留 deprecation 别名
([#2619](https://github.com/Motphys/UniLab/issues/2619))。
- Remove zero-consumer public surface identified by the repo-wide YAGNI scan
([#2629](https://github.com/Motphys/UniLab/issues/2629)): the
`clear_finite_verdict` alias on the observation/action/reward managers,
`TerminationManager.dones` / `TerminationManager.get_term`,
`RecorderManager.__contains__` (and the Null variant), `DelayBuffer.set_lags`,
`apply_cuda_process_sharing_manifest`, `get_hydra_runtime_choice` (and its
`unilab.training` re-export), `registry.find_available_sim_backend`,
`MotionLoader.get_clip_indices`, the `VizCfg`/`viz` field on
`UniformVelocityCommandCfg`, `BaseActionCfg.preserve_order`, the
`Sequence[str]` branch of `resolve_checkpoint_file`, the
`resolve_torch_device_alias` group in `rl.runtime.device`, the ignored
`num_envs` parameter of `build_actor`, and the silently ignored `algo_name`
parameter of `EnvConfigAdapter` (its forwarding parameter on
`build_play_backend_adapter` is removed as well). Owner YAML cleanup: drop
the never-consumed PPO `algo.experiment_name` / `algo.run_name` and the SAC
`algo.actor: {}` fake-compat key, plus motion-tracking owner YAML lines that
only restate dataclass defaults (`sampling_start_ratio`, `joint_position_range`,
`joint_default_position_range`).
删除全仓 YAGNI 扫描确认的零消费公共面
([#2629](https://github.com/Motphys/UniLab/issues/2629)):observation /
action / reward manager 上的 `clear_finite_verdict` 别名、
`TerminationManager.dones` / `TerminationManager.get_term`、
`RecorderManager.__contains__`(含 Null 版)、`DelayBuffer.set_lags`、
`apply_cuda_process_sharing_manifest`、`get_hydra_runtime_choice`(及其
`unilab.training` re-export)、`registry.find_available_sim_backend`、
`MotionLoader.get_clip_indices`、`UniformVelocityCommandCfg` 上的
`VizCfg`/`viz` 字段、`BaseActionCfg.preserve_order`、
`resolve_checkpoint_file` 的 `Sequence[str]` 分支、`rl.runtime.device` 中的
`resolve_torch_device_alias` 整组、`build_actor` 被静默忽略的 `num_envs`
参数,以及 `EnvConfigAdapter` 被静默忽略的 `algo_name` 参数(其转发参数
`build_play_backend_adapter.algo_name` 一并移除)。owner YAML 清理:删除
从未被消费的 PPO `algo.experiment_name` / `algo.run_name` 与 SAC
`algo.actor: {}` 假兼容键,以及仅重复 dataclass 默认值的 motion-tracking
owner YAML 行(`sampling_start_ratio`、`joint_position_range`、
`joint_default_position_range`)。
- Second YAGNI batch from the downstream-ecosystem audit in issue #2629 (all
previously "maintainer decision" items, now confirmed deletable): the
`init_velocity_prob` fake knob on `UniformVelocityCommandCfg` (all eight
owner YAML lines removed; the five downstream repos that still write
`init_velocity_prob: 0.0` must drop those lines on upgrade, tracked in the
issue), the never-consumed `action_low` / `action_high` / `joint_names`
reserved fields on `EnvAlgoCapabilities`, the tensor-migration leftovers
`motion_tracking/common/tensor_runtime.py`,
`motion_tracking/common/tensor_state_store.py` (`DeviceStateStore`), and
`locomotion/go2/tensor_parity.py` (ADR-0011/0012 evidence pointers updated),
the PPO-owner `algo.resume` / `algo.resume_path` dead keys (the PPO
entrypoint now fails closed via `reject_removed_ppo_resume_keys`; PPO
resume stays on `algo.load_run` + `algo.checkpoint`; the off-policy owners
still own the live keys), the silently dropped `label` argument of
`TorchEnv.record_finite_validation`, the tests-only debug surface
(`ManagerBase.get_active_iterable_terms` and its manager implementations,
`extract_reset_obs`, the `render_play_mode` and
`run_native_viewer_play_loop` thin wrappers — callers use
`env.run_playback` directly — and `OnPolicyLogger` with its api_reference
entry), and the zero-consumer noise cfgs `ConstantNoiseCfg`,
`GaussianNoiseCfg`, and `SegmentwiseUniformNoiseCfg` (`UniformNoiseCfg` and
the `NoiseModel` extension base stay).
issue #2629 下游生态审计复核后的第二批 YAGNI 删除(原"维护者决策"项全部
转删除):`UniformVelocityCommandCfg` 的假旋钮 `init_velocity_prob`(8 个
owner YAML 行同步删除;5 个下游仓库仍需在升级时删掉各自 YAML 中的
`init_velocity_prob: 0.0`,见 issue 跟踪);`EnvAlgoCapabilities` 上从未被
消费的预留字段 `action_low` / `action_high` / `joint_names`;tensor 迁移
遗留三模块(`motion_tracking/common/tensor_runtime.py`、
`motion_tracking/common/tensor_state_store.py` 的 `DeviceStateStore`、
`locomotion/go2/tensor_parity.py`,ADR-0011/0012 证据引用已同步);PPO
owner 的死键 `algo.resume` / `algo.resume_path`(PPO 入口经
`reject_removed_ppo_resume_keys` fail-closed;PPO resume 仍走
`algo.load_run` + `algo.checkpoint`;off-policy owner 继续拥有活键);
`TorchEnv.record_finite_validation` 被静默丢弃的 `label` 参数;仅 tests
消费的调试面(`ManagerBase.get_active_iterable_terms` 及其各 manager 实现、
`extract_reset_obs`、`render_play_mode` 与
`run_native_viewer_play_loop` 薄封装——调用方改为直接使用
`env.run_playback`——以及 `OnPolicyLogger` 及其 api_reference 条目);
零消费的 noise cfg(`ConstantNoiseCfg`、`GaussianNoiseCfg`、
`SegmentwiseUniformNoiseCfg`;保留 `UniformNoiseCfg` 与 `NoiseModel`
扩展基座)。

## 1.5.11 (2026-11-16)

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,8 @@ CUDA_VISIBLE_DEVICES=1 uv run train --algo sac --task g1_motion_tracking --sim m
training.use_amp=true algo.seed=1 \
env.commands.motion.params.motion_file=motions/g1/motion_crawl_slope_uni.npz \
env.scene.model_file=src/unilab/assets/robots/g1/scene_crawl_slope.xml \
env.commands.motion.params.sampling_mode=start \
env.commands.motion.params.sampling_mode=mixed \
env.commands.motion.params.sampling_start_ratio=1.0 \
env.commands.motion.params.truncate_on_clip_end=true \
env.max_episode_seconds=20.0 \
'env.commands.motion.params.pose_range={x:[0,0],y:[0,0],z:[0,0],roll:[0,0],pitch:[0,0],yaw:[0,0]}' \
Expand All @@ -120,9 +121,10 @@ CUDA_VISIBLE_DEVICES=1 uv run train --algo sac --task g1_motion_tracking --sim m
Key overrides: `env.commands.motion.params.motion_file` selects the crawl-slope
clip; `env.scene.model_file` switches to the slope scene
(`scene_crawl_slope.xml` exists under `src/unilab/assets/robots/g1/`);
`sampling_mode=start` plus `truncate_on_clip_end=true` starts from the clip
beginning and truncates there; and zeroing the command reset ranges reuses the
exact clip initial state.
`sampling_mode=mixed` with `sampling_start_ratio=1.0` plus
`truncate_on_clip_end=true` starts every episode from the clip beginning and
truncates there; and zeroing the command reset ranges reuses the exact clip
initial state.

## Interactive Debugging

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,8 @@ CUDA_VISIBLE_DEVICES=1 uv run train --algo sac --task g1_motion_tracking --sim m
training.use_amp=true algo.seed=1 \
env.commands.motion.params.motion_file=motions/g1/motion_crawl_slope_uni.npz \
env.scene.model_file=src/unilab/assets/robots/g1/scene_crawl_slope.xml \
env.commands.motion.params.sampling_mode=start \
env.commands.motion.params.sampling_mode=mixed \
env.commands.motion.params.sampling_start_ratio=1.0 \
env.commands.motion.params.truncate_on_clip_end=true \
env.max_episode_seconds=20.0 \
'env.commands.motion.params.pose_range={x:[0,0],y:[0,0],z:[0,0],roll:[0,0],pitch:[0,0],yaw:[0,0]}' \
Expand All @@ -113,8 +114,9 @@ CUDA_VISIBLE_DEVICES=1 uv run train --algo sac --task g1_motion_tracking --sim m

关键覆写:`env.commands.motion.params.motion_file` 切换爬坡动作;
`env.scene.model_file` 切换斜坡场景(`scene_crawl_slope.xml` 在
`src/unilab/assets/robots/g1/` 下);`sampling_mode=start` 加
`truncate_on_clip_end=true` 从 clip 起点出发并在结尾截断;command reset 范围全置零
`src/unilab/assets/robots/g1/` 下);`sampling_mode=mixed` 且
`sampling_start_ratio=1.0`,再加 `truncate_on_clip_end=true`,每个 episode 都从 clip
起点出发并在结尾截断;command reset 范围全置零
即可复用 motion 的精确初始状态。

## 交互式调试
Expand Down
1 change: 0 additions & 1 deletion scripts/benchmark/benchmark_drake_performance.py
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,6 @@ def _compose_env_cfg(task: str, backend: str, spec: TaskSpec) -> Any:
env_cfg_override = EnvConfigAdapter(
owner_cfg,
root_dir=ROOT_DIR,
algo_name="ppo",
).build_task_env_cfg_override()
cfg = spec.env_cfg_factory()
apply_cfg_overrides(cfg, env_cfg_override)
Expand Down
1 change: 0 additions & 1 deletion scripts/benchmark/env/benchmark_env_step.py
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,6 @@ def _owner_yaml_cfg(
env_cfg_override = EnvConfigAdapter(
owner_cfg,
root_dir=ROOT_DIR,
algo_name=algo_name,
).build_task_env_cfg_override()

cfg = env_cfg_cls()
Expand Down
4 changes: 1 addition & 3 deletions scripts/benchmark/env/benchmark_env_step_phase_cpu.py
Original file line number Diff line number Diff line change
Expand Up @@ -102,9 +102,7 @@ def main(argv: Sequence[str] | None = None) -> int:
overrides=[f"task={args.task}", f"algo.num_envs={args.num_envs}"],
)
OmegaConf.resolve(cfg)
env_cfg_override = EnvConfigAdapter(
cfg, root_dir=REPO_ROOT, algo_name=str(cfg.algo.algo)
).build_task_env_cfg_override()
env_cfg_override = EnvConfigAdapter(cfg, root_dir=REPO_ROOT).build_task_env_cfg_override()
if args.cpu_ids is not None:
env_cfg_override = {
**(env_cfg_override or {}),
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1133,7 +1133,6 @@ def _build_and_run_case(
env_cfg_override = EnvConfigAdapter(
cfg,
root_dir=ROOT_DIR,
algo_name=algo,
).build_task_env_cfg_override()

env = None
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -319,7 +319,6 @@ def _resolve_env_shape(cfg: DictConfig, algo: str) -> ReplayShape:
env_cfg_override = EnvConfigAdapter(
cfg,
root_dir=ROOT_DIR,
algo_name=algo,
).build_task_env_cfg_override()
env = create_env(cfg, num_envs=1, env_cfg_override=env_cfg_override)
try:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -262,7 +262,6 @@ def _resolve_env_shape(cfg: DictConfig) -> ReplayShape:
env_cfg_override = EnvConfigAdapter(
cfg,
root_dir=ROOT_DIR,
algo_name="sac",
).build_task_env_cfg_override()
env = create_env(cfg, num_envs=1, env_cfg_override=env_cfg_override)
try:
Expand Down
4 changes: 1 addition & 3 deletions scripts/benchmark/torch_env/g1_flashsac_backend.py
Original file line number Diff line number Diff line change
Expand Up @@ -183,9 +183,7 @@ def _build_cfg(backend: str, num_envs: int, *, isaacsim_test_fixture: bool = Fal
"hydra/hydra_logging=disabled",
],
)
override = EnvConfigAdapter(
owner_cfg, root_dir=ROOT_DIR, algo_name="flashsac"
).build_task_env_cfg_override()
override = EnvConfigAdapter(owner_cfg, root_dir=ROOT_DIR).build_task_env_cfg_override()
cfg = ManagerBasedRlEnvCfg()
apply_cfg_overrides(cfg, override)
return cfg
Expand Down
7 changes: 2 additions & 5 deletions scripts/visualize_task_env.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
Mujoco backend: stitches all `--num_envs` robot replicas into the same scene
and drives every replica's qpos/qvel each frame from `env.get_physics_state_snapshot()`.

Motrix backend: delegates to `render_play_mode`, whose native renderer lays
Motrix backend: delegates to `env.run_playback`, whose native renderer lays
all `num_envs` robots out on a grid using `cfg.render_spacing`.

Usage:
Expand Down Expand Up @@ -103,8 +103,6 @@ def _stitch_replicas(parent_scene_xml: Path, robot_base_xml: Path, env_origins:


def _run_motrix(env, num_envs: int) -> None:
from unilab.visualization import render_play_mode

actions = np.zeros((num_envs, env.action_space.shape[0]), dtype=np.float32)
camera_kwargs = _motrix_camera_kwargs(env, num_envs)

Expand All @@ -114,8 +112,7 @@ def initialize():
def step(_obs):
return env.step(actions)

render_play_mode(
env,
env.run_playback(
initialize=initialize,
step=step,
num_steps=None,
Expand Down
17 changes: 5 additions & 12 deletions src/unilab/assets/hub.py
Original file line number Diff line number Diff line change
Expand Up @@ -135,23 +135,16 @@ def resolve_motion_files(
return [_resolve_single(p, repo_id=_HF_MOTIONS_REPO_ID) for p in motion_file]


def resolve_checkpoint_file(
checkpoint_file: str | Sequence[str],
) -> str | list[str]:
"""Ensure checkpoint file(s) exist locally, downloading from HF if needed.
def resolve_checkpoint_file(checkpoint_file: str) -> str:
"""Ensure a checkpoint file exists locally, downloading from HF if needed.

Args:
checkpoint_file: Absolute path or ``ASSETS_ROOT_PATH``-relative path
(single string or sequence of strings).
checkpoint_file: Absolute path or ``ASSETS_ROOT_PATH``-relative path.

Returns:
Resolved absolute path(s) guaranteed to exist on disk.
A single string input returns a single string; a sequence input
returns a list of strings.
Resolved absolute path guaranteed to exist on disk.
"""
if isinstance(checkpoint_file, str):
return _resolve_single(checkpoint_file, repo_id=_HF_CHECKPOINTS_REPO_ID)
return [_resolve_single(p, repo_id=_HF_CHECKPOINTS_REPO_ID) for p in checkpoint_file]
return _resolve_single(checkpoint_file, repo_id=_HF_CHECKPOINTS_REPO_ID)


def _resolve_single(
Expand Down
2 changes: 0 additions & 2 deletions src/unilab/base/config_adapter.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,10 @@ def __init__(
cfg: DictConfig,
*,
root_dir: str | Path,
algo_name: str | None = None,
scene_materializer: Callable[..., str] = materialize_scene_visual_override,
) -> None:
self.cfg = cfg
self.root_dir = Path(root_dir)
self.algo_name = algo_name
self.scene_materializer = scene_materializer

def build_task_env_cfg_override(self) -> dict[str, Any]:
Expand Down
18 changes: 0 additions & 18 deletions src/unilab/base/contracts/env.py
Original file line number Diff line number Diff line change
Expand Up @@ -83,21 +83,6 @@ class EnvAlgoCapabilitiesProtocol(Protocol):
``step``/``reset`` hot loops.
"""

@property
def action_low(self) -> torch.Tensor | None:
"""Per-dimension lower action bounds, shape ``(action_dim,)``."""
...

@property
def action_high(self) -> torch.Tensor | None:
"""Per-dimension upper action bounds, shape ``(action_dim,)``."""
...

@property
def joint_names(self) -> tuple[str, ...] | None:
"""Joint names in action order, for symmetry-augmentation maps."""
...

@property
def reward_component_names(self) -> tuple[str, ...] | None:
"""Reward component names for fixed-width device metric aggregation."""
Expand All @@ -108,9 +93,6 @@ def reward_component_names(self) -> tuple[str, ...] | None:
class EnvAlgoCapabilities:
"""Default capability carrier with every field unset."""

action_low: torch.Tensor | None = None
action_high: torch.Tensor | None = None
joint_names: tuple[str, ...] | None = None
reward_component_names: tuple[str, ...] | None = None


Expand Down
6 changes: 3 additions & 3 deletions src/unilab/base/entity.py
Original file line number Diff line number Diff line change
Expand Up @@ -1943,7 +1943,7 @@ def __init__(
# When the owning env defers finite validation, per-step write checks
# accumulate into the env's device-resident verdict instead of
# synchronizing on every call; the env's poll boundary raises.
self._finite_validation_recorder: Callable[[torch.Tensor, str], None] | None = None
self._finite_validation_recorder: Callable[[torch.Tensor], None] | None = None
self._interval_operand_device_value: torch.device | None = None
self._interval_root_body_ids_value: torch.Tensor | None = None
self._body_tensor_layouts: dict[tuple[str, ...], np.ndarray] = {}
Expand Down Expand Up @@ -2171,7 +2171,7 @@ def motion_body_ids(self) -> np.ndarray:
return self._motion_body_ids

def set_finite_validation_recorder(
self, recorder: Callable[[torch.Tensor, str], None] | None
self, recorder: Callable[[torch.Tensor], None] | None
) -> None:
"""Route per-step tensor-write finite verdicts into the env boundary.

Expand Down Expand Up @@ -4269,7 +4269,7 @@ def _validate_body_wrench_values(
)
recorder = self._finite_validation_recorder
if recorder is not None:
recorder(values, f"{term_name} body {label}")
recorder(values)
elif not bool(torch.isfinite(values).all()):
raise ValueError(
f"EventManager term '{term_name}' body {label} must be finite floating data"
Expand Down
Loading
Loading