普通中文说明
本 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_sim、write_root_link_pose_to_sim、write_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 行手写改动。
普通中文说明
本 issue 只交付一个结果:让 Manager-Based entity 能通过正式
SimBackendcontract,在同一个 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 行。永久维护成本是一项
SimBackendroot-state layout contract、各 backend 的显式实现/unsupported 诊断,以及 entity/reset transaction 的 NumPy facade。Umbrella: #1042
In scope
SimBackend声明 typed root-state layout contract;明确 publicset_state中 free-root qpos 为 xyz+wxyz,qvel 为 world linear + body angular。root_body_name解析 free-root qpos/qvel columns;fixed/non-free/missing root fail closed。NotImplementedError,不猜 body id 或列偏移。EntityData.default_root_state提供只读(num_envs, 13)NumPy 默认值;world angular velocity 从 backend qvel 正确转换。Entity.write_root_state_to_sim、write_root_link_pose_to_sim、write_root_link_velocity_to_sim只写 env-ownedResetStateTransaction,不直接调用 backend 私有对象。SimBackend.set_state;pose 后的 velocity conversion 使用 transaction 中已暂存的 quaternion。Acceptance
make test-all通过。Stop conditions
getattr/hasattr探测能力。NpEnvState、runner、IPC 或SimBackend.set_state的单次 transaction ownership。