Skip to content

Backend: 建立 Manager-Based root-state reset contract #1072

Description

@TATP-233

普通中文说明

本 issue 只交付一个结果:让 Manager-Based entity 能通过正式 SimBackend contract,在同一个 reset transaction 中读取默认 root state 并暂存 root pose/velocity 写入。

社区 root state 是 13 维:世界系 position(3)、wxyz quaternion(4)、世界系 linear velocity(3)、世界系 angular velocity(3)。backend 的 generalized state 布局并不相同:MuJoCo/MJWarp 使用 free-joint qpos/qvel,Motrix 可能有多个 floating base 且内部四元数为 xyzw,Drake 当前 runtime metadata 未声明 body→free-root 映射。本 issue 在 backend 冷路径解析并缓存这些差异;不允许 env/entity 猜“前 7/6 列”。

不实现 reset_root_state_uniform,不迁移 production task,不新增 mocap/fixed-base 写能力,不改 runner、IPC、训练脚本或 Hydra routing。

预计 8–12 个文件、UniLab-specific 手写改动不超过 1,200 行。永久维护成本是一项 SimBackend root-state layout contract、各 backend 的显式实现/unsupported 诊断,以及 entity/reset transaction 的 NumPy facade。

Umbrella: #1042

In scope

  • SimBackend 声明 typed root-state layout contract;明确 public set_state 中 free-root qpos 为 xyz+wxyz,qvel 为 world linear + body angular。
  • MuJoCo、Motrix、MJWarp 在 init/materialization 冷路径按 root_body_name 解析 free-root qpos/qvel columns;fixed/non-free/missing root fail closed。
  • Drake 只有在现有 runtime metadata 足以证明 body→root 映射时实现;否则通过正式方法显式 NotImplementedError,不猜 body id 或列偏移。
  • EntityData.default_root_state 提供只读 (num_envs, 13) NumPy 默认值;world angular velocity 从 backend qvel 正确转换。
  • Entity.write_root_state_to_simwrite_root_link_pose_to_simwrite_root_link_velocity_to_sim 只写 env-owned ResetStateTransaction,不直接调用 backend 私有对象。
  • transaction 支持多个 event term 组合,最终仍只调用一次 SimBackend.set_state;pose 后的 velocity conversion 使用 transaction 中已暂存的 quaternion。
  • capability/layout、shape、dtype、finite、env id、quaternion 风险在最近边界 fail closed;backend unsupported 结论在 materialization 时缓存,reset 热路径不解析 asset/XML/name metadata。

Acceptance

  • focused tests 覆盖 13-D 默认值、world↔body angular conversion、pose/velocity 组合、局部 env reset、单次 commit、失败时不提交。
  • backend focused/conformance tests 覆盖 MuJoCo 与 Motrix 非首列/多 floating-base layout;MJWarp layout;Drake 显式 supported 或 unsupported 事实。
  • fixed-base、错误 body、错误 layout、shape/dtype/NaN/Inf、非单位/退化 quaternion 均有明确诊断。
  • 现有 joint reset transaction、entity facade、backend tests 不回归。
  • ruff、mypy、pyright、focused tests 与 make test-all 通过。

Stop conditions

  • 需要在 reset/step 热路径读取 XML、asset 或按名字查询 backend model。
  • 需要 entity 调用 backend 子类私有方法,或使用 getattr/hasattr 探测能力。
  • 需要把实际 event sampling、mocap mutation或 production task migration 混入本 PR。
  • 需要改变 NpEnvState、runner、IPC 或 SimBackend.set_state 的单次 transaction ownership。
  • 超过 12 个非删除文件或 1,200 行手写改动。

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions