调研报告：Holosoma 如何统一 MuJoCo / IsaacGym / IsaacSim 物理后端

[TATP-233]

调研报告：Holosoma 如何统一 MuJoCo / IsaacGym / IsaacSim 物理后端

摘要

Holosoma 的“统一物理后端”不是把几个引擎包装成同名的 step()，而是形成了一条完整闭环：

配置选择（simulator registry / _target_）
  -> 统一模拟器前门（BaseSimulator）
  -> 统一状态语义（frame / quaternion / shape / ordering）
  -> 语义对象注册表（ObjectRegistry）
  -> 后端边界转换（IsaacGym / IsaacSim / MuJoCo）
  -> 生命周期扩展（hooks / plugins）
  -> 同场景跨后端行为测试

其中最重要的不是继承关系，而是三件事：

1. 任务只依赖稳定的物理语义，例如状态在哪个坐标系、四元数顺序、批维和对象顺序；
2. 引擎差异在 adapter 边界被吸收，绝对 actor index、freejoint 局部角速度、四元数顺序等不泄漏给任务；
3. 一致性用真实物理行为验证，而不是只验证 API 能调用或写入后能读回。

它也并非完全消除了后端分支：初始化时序、domain randomization 和绘制等路径仍有 hasattr / simulator type switch，宽基类中也仍有 NotImplementedError。这些是 UniLab 不宜照搬的部分。

本文是源码审计，不是跨引擎数值精度或性能 benchmark。审计基线：

• amazon-far/holosoma@6761e2b
• unilabsim/UniLab@21dbe46

1. 配置负责选择后端，任务负责统一编排

Holosoma 用 SIMULATOR_REGISTRY 把逻辑名称映射到 concrete config：

• isaacgym -> IsaacGym
• isaacsim -> IsaacSim
• mujoco -> MuJoCo + classic
• mjwarp -> MuJoCo + warp

这里 mjwarp 不是第四套任务接口，而是复用 MuJoCo facade、只替换其内部计算后端。注册与默认配置见 config_values/simulator.py#L10-L111。

BaseTask 根据 _target_ 动态构造 simulator，再统一执行：

setup -> setup_terrain -> load_assets -> create_envs -> prepare_sim

任务层因此掌握生命周期顺序，但不知道 backend constructor 的细节：base_task.py#L89-L190。

这解决的是“从配置得到哪个实现”和“各实现按什么生命周期启动”两个问题；它本身还没有解决状态语义是否真的一致。

2. BaseSimulator 是任务访问物理世界的统一前门

BaseSimulator 汇集了场景和资产创建、仿真 step/refresh、控制、actor/object state、camera/sensor、viewer/bridge 等入口：base_simulator.py#L31-L116、base_simulator.py#L249-L467。具体的 IsaacGym、IsaacSim、MuJoCo 类实现这个前门。

MuJoCo 内部还有第二层 facade：顶层 MuJoCo 对任务隐藏 classic 与 warp 的差异，IMujocoBackend 再约束 ClassicBackend / WarpBackend。adapter 可以按数据驻留位置选择 zero-copy fast path 或 CPU slow path，任务代码不需要感知：mujoco/backends/base.py、mujoco.py#L292-L343。

所以它实际有两层变化轴：

task
  -> BaseSimulator
       -> IsaacGym
       -> IsaacSim
       -> MuJoCo facade
            -> ClassicBackend
            -> WarpBackend

3. 真正的 contract 是状态语义，而不是方法名

Holosoma 把 actor root state 固定为：

[N, 13] =
[x, y, z,
 qx, qy, qz, qw,
 vx, vy, vz,
 wx, wy, wz]

并进一步约束：

• position、linear velocity、angular velocity 都是 world frame；
• quaternion 为 xyzw；
• 按名字批量查询时，结果是 name-major / env-minor；
• get/set 顺序必须对称；
• environment origin offset 在 backend 边界处理，调用方不按 backend 修正；
• 延迟写入通过 write_state_updates() 显式 flush。

这些约束直接写在 BaseSimulator actor state API 中：base_simulator.py#L842-L1028、base_simulator.py#L1033-L1170。UnifiedRootStatesView 又为旧式 tensor 使用方式提供相同的逻辑视图：root_states_view.py#L1-L114。

adapter 的价值体现在“原生表示不一致”时：

• MuJoCo freejoint 的 angular velocity 是 body-local，读取和写入时必须在边界转换为统一的 world frame；
• IsaacGym 可以直接索引 root state tensor，但仍需按统一的名字/环境顺序组装；
• IsaacSim 通过对象级 state adapter 读写，并在原生 wxyz 与 contract xyzw 间转换。

实现证据分别见 MuJoCo get/set actor state、IsaacGym get/set actor state、IsaacSim get/set actor state。

一个值得保留的判断是：同样叫 get_actor_state() 并不代表统一；只有 frame、quaternion、shape、ordering、写入可见性都一致，才是可替换的 contract。

4. ObjectRegistry 把 backend 物理索引变成语义地址

不同引擎对 actor/object 的创建顺序和绝对索引不一致。Holosoma 不让任务持有这些物理索引，而是引入 ObjectRegistry：

• 对象按 ROBOT、静态 SCENE、可自由运动的 INDIVIDUAL 分类；
• backend 只报告实际 spawn 的对象，共享层负责排序、分类、编号和注册；
• 虚拟地址按 env interleaved：[env0_objects][env1_objects]...；
• 名称查询 API 对外仍返回 name-major / env-minor；
• registry 同时维护 name 到虚拟 index、反向解析以及初始 pose/velocity。

因此绝对物理索引可以因 backend 而不同，任务依赖的名字和虚拟地址不变。数据结构与索引规则见 object_registry.py#L39-L150、object_registry.py#L280-L455，共享注册模板见 base_simulator.py#L320-L377。

这相当于在 simulator API 上建立了一个稳定的“虚拟地址空间”，是多 actor 任务能跨后端复用的重要前提。

5. 配置只统一真正同义的字段

Holosoma 没有把所有引擎参数拍平成一组看似通用的标量：

• PhysicsConfig 的核心只放 mass/density；
• 两个 PhysX 后端真正同义的参数放在共享 physx 块；
• 语义不同的参数留在 isaacgym / isaacsim / mujoco 原生配置块；
• friction 没有被假设成一个在所有引擎中完全等价的数值。

配置结构见 config_types/scene.py#L17-L182。

资产侧支持 USD / URDF / XML 多格式候选，由 shared selector 根据 backend 支持列表选择；无支持格式时直接报错，而不是静默 fallback：asset_format.py#L1-L70。这体现了一个重要边界：统一的是选择协议和失败语义，不是强行让每个引擎接受同一种原生资产。

6. hooks/plugins 统一 side effects，而不复制 step loop

Holosoma 定义了以下 lifecycle phase：

FRAME_BEGIN -> PRE_STEP -> POST_STEP -> FRAME_END
EPISODE_START / EPISODE_END / CLOSE

hook manager 校验 callback arity，保持 deterministic registration order，支持 frequency cadence，并在 close 时逆序清理：hooks.py#L11-L205。BaseTask 与直接使用 simulator 的路径发出同一组 phase：base_task.py#L441-L470。

camera、录制、遥操作、bridge 等横切能力因此可以注册到生命周期，而不是各自复制或侵入训练 step loop。例如 camera producer 先注册 FRAME_END，消费者插件后注册，就能通过注册顺序保证读到本帧 fresh buffer。

相关设计演进可见 hooks PR #158、plugins PR #160、scene/object abstraction PR #147、cross-backend DR PR #162、camera PR #170。

7. 跨后端测试验证“发生了相同的物理行为”

Holosoma 把同一组行为场景复用于各 backend wrapper，覆盖：

• 自由落体；
• 碰撞与接触；
• 摩擦滑移；
• restitution 反弹；
• reset 与对象状态 get/set；
• 多 environment 之间的独立性。

入口分别见 test_behavior_mujoco.py#L1-L121、test_behavior_isaacgym.py#L1-L94、test_behavior_isaacsim.py#L1-L71。不支持的 backend × behavior 组合显式 skip 并记录原因，而不是从矩阵中静默消失。

这类测试比“setter 后 getter 返回同一个值”更有价值，因为后者只能证明存储/API 自洽，不能证明 frame conversion、接触参数或 step semantics 正确。

8. 统一层仍有泄漏与债务

Holosoma 的实现应视为有价值的工程样本，而不是可以原样复制的最终形态：

1. BaseTask 仍通过 hasattr(self.simulator, "gym") 区分 IsaacGym 的初始化时序：base_task.py#L132-L162。这说明 lifecycle contract 还不完整。
2. 部分 domain randomization term 读取 get_simulator_type() 后直接调用 backend native API：randomization/terms/objects.py#L180-L312。这破坏了 dependency inversion。
3. BaseSimulator 较宽，许多可选能力靠 NotImplementedError 或测试 skip 表达，而不是显式 capability object。
4. 个别接口的 shape 仍未完全统一；例如 DOF state 文档承认 IsaacGym 是 flattened tensor、IsaacSim 是 3-D tensor。
5. 全局 simulator type 仍用于 import ordering、drawing、DR 等外围路径。

所以它做到了“主体任务可跨引擎复用”，但还没有做到“所有上层代码只依赖纯 contract”。

9. 与 UniLab 当前设计的对照

维度	Holosoma	UniLab main@21dbe46	判断
后端入口	宽 BaseSimulator + concrete simulators	SimBackend(abc.ABC)	UniLab 的必选 contract 更严格，不应退回 duck typing
后端选择	registry + _target_	owner YAML + env registry + lazy create_backend	保留 UniLab 的 config-first 路径
状态语义	actor 13-vector，world frame，xyzw	base/body contract 明确 world frame，quaternion 为 wxyz	不必统一成同一种 quaternion；应固定各自 contract 并跨后端测试
多 actor/object	ObjectRegistry + virtual index	以 name -> body id 为主，尚无通用 actor registry	仅在多 actor 产品需求出现时增量引入
capabilities	多处由 NotImplementedError / skip 表达	已有 DR 与 play capability object	UniLab 更适合继续扩展显式 capability
lifecycle	typed hooks/plugins	主要由 env/backend/runner 直接编排	hooks 是最值得补齐的横切扩展点
验证	同一物理场景跑多个 backend	已有 contract/smoke/task tests	可补 task/scenario × backend behavior matrix
backend 泄漏	初始化、DR 等仍有 type switch	仓库规范明确要求 backend isolation	不照搬 hasattr 或 simulator type switch

UniLab 已有的基础包括：

• SimBackend 统一 step/set_state、base/body state、sensor、DR、playback 等 contract，并明确 base position/velocity 的 world frame 与 quaternion wxyz：base/backend/base.py#L58-L317、base/backend/base.py#L435-L478；
• BackendPlayCapabilities 和 DR capabilities 已显式暴露支持面，而不是让 env 猜 backend class；
• NpEnv.step() 只通过 _backend.step() 推进物理：np_env.py#L171-L245；
• create_backend() 集中处理 lazy import 和 constructor routing：base/backend/__init__.py#L92-L187；
• registry 允许同一个 environment name 按 backend 注册实现：registry.py#L39-L124；
• SceneCfg 当前只声明 model、fragments、terrain 与 visual override，是较薄的冷路径配置：scene.py#L8-L29。

换句话说，UniLab 不缺一个新的顶层 BaseSimulator；更值得补的是 contract 的覆盖范围、生命周期扩展点和跨后端行为证据。

10. 对 UniLab 的建议

以下是基于本次审计的设计建议，不代表已经批准的实现 roadmap。

A. 保持现有 owner config 与 SimBackend 边界

继续由 task=<task>/<backend> owner config 选择完整可运行组合；training.sim_backend 只作为身份/一致性字段。env 热路径不根据 backend string、class name 或 hasattr 切换实现。

B. 先补语义 contract，再补方法

每个新增 contract 都应同时写清：

shape + dtype + device/ownership + frame + quaternion order
+ name/index ordering + get/set symmetry + write visibility
+ unsupported/fallback behavior

UniLab 当前 wxyz contract 没有必要为了模仿 Holosoma 改成 xyzw；关键是所有 backend adapter 在边界转换、同一测试矩阵验证。

C. capability-first，避免继续扩大宽基类

对资产格式、actor state write、sensor、renderer、video、DR 等可选能力，优先扩展 typed capability/plan，而不是让上层捕获 NotImplementedError，也不要从 backend_type 推断支持情况。配置解析时就应 fail loudly 或给出明确 warning。

D. 多 actor/object registry 按实际需求增量建设

如果路线图出现物体操作、动态障碍或多 actor 场景，可以借鉴 ObjectRegistry 的语义 name + virtual index：backend 在冷路径报告实体，共享层生成稳定映射，热路径只用缓存 ID。若任务始终是单机器人 locomotion，则不应为了架构对称先复制 all_root_states proxy。

E. 引入小而明确的 lifecycle phase

优先考虑 PRE_STEP / POST_STEP / EPISODE_START / EPISODE_END / CLOSE 等最小集合，并定义：注册顺序、异常策略、调用频率、资源逆序释放。录制、观测采集、遥操作、profiling 等 side effect 通过 phase 扩展，避免 runner/env/backend 各自复制 step loop。

F. 建立 scenario × backend 行为矩阵

为同一个 task/scenario 在 MuJoCo、Mjwarp、Motrix、Drake 等被声明支持的 backend 上复用行为断言，至少覆盖：

• gravity / contact / reset；
• base pose/velocity 的 frame 与 quaternion；
• action-to-step 与 substep 语义；
• per-env independence；
• sensor timing；
• 已支持的 DR 项实际改变物理结果。

不支持的格子必须记录明确原因。容差应按物理量和 backend 定义，不能要求不同 solver trajectory bitwise equal。

G. 坚守冷热路径边界

资产解析、name -> id、model metadata、shape/capability 检查在构造/materialize 阶段完成并缓存；step()、observation、reward、reset 热路径只使用已解析的数组、ID 和 callable。这样既保持 backend isolation，也避免统一层引入额外性能税。

结论

Holosoma 的可迁移价值不在于一个“大而全”的基类，而在于它把统一后端拆成了 选择、语义、寻址、生命周期、适配、验证 六个相互闭合的 contract。UniLab 已经有更严格的 SimBackend、owner config 和 capability 基础，下一步若要增强跨后端一致性，应优先补 lifecycle 与 behavior matrix，并在真实多 actor 需求出现时再引入语义对象注册表；不要把 Holosoma 残留的 simulator type switch、hasattr 分支或宽接口一并复制过来。