审计：unisim 各物理后端的 Domain Randomization（DR）支持矩阵与差距

[TATP-233]

审计：unisim 各物理后端的 Domain Randomization（DR）支持矩阵与差距

背景与方法

UniLab 的 DR 生命周期由 Manager-Based event terms 通过 SimBackend.get_dr_capabilities() 协商（不支持的能力 fail closed）。本文对 unisim 当前源码中 9 个已声明适配器的 DR 能力做了一次源码级审计，依据为：

• 各后端 get_dr_capabilities() 实现（权威实例声明，见 src/unisim/backend/<engine>/backend.py）
• unisim.dr.types 的 term 目录：16 个 reset terms、5 个内置 interval terms（push / body_linear_velocity_delta / body_angular_velocity_delta / body_force / body_torque，另支持自定义 op）、fixed variants（same_layout / uniform_public_layout）、per-env playback
• unisim.support 的静态语义清单（entity.multiple 等特性中带条件的 DR 描述）

注意：声明 ≠ 运行时验证。表中为适配器自我声明的支持面；带 * 的条目依赖实例状态或引擎运行时标志。

Reset DR（16 项，重置时按环境写模型参数）

后端	支持的 reset terms	关键缺口
mujoco	全部 16 项	—
mjwarp	全部 16 项	—
isaacsim（mapped 场景）	11 项：geom_friction, kp, kd, body_mass, body_inertia, body_ipos, base_mass_delta, base_com_offset, dof_damping, dof_armature, dof_frictionloss	gravity（PhysX 重力是 sim 全局）、body_iquat（PhysX 由惯性张量推导主轴系）、geom_size/geom_solref/geom_solimp（PhysX 无对应通道）均 fail closed；非 mapped 路径为空
isaacgym（mapped 场景）	8 项：kp, kd, body_mass, body_inertia, body_ipos, dof_armature, dof_frictionloss, geom_friction	无 gravity（sim 全局）、dof_damping（PhysX 关节阻尼仅 drive 内）、base_mass_delta/base_com_offset（多 root 场景无单一 base）、geom_size/solref/solimp；legacy 裸 MJCF 路径为空
genesis（portable 模式）	9 项：body_mass, base_mass_delta, body_ipos, base_com_offset, kp, kd, dof_damping, dof_frictionloss, dof_armature	geom_friction 不支持（Genesis 仅有 per-env 比例 API，无绝对值接口）；无 gravity；非 portable 模式退化为 4 项（body_mass, base_mass, kp, kd）
motrix（portable 模式）	条件支持：body_mass/base_mass_delta*、body_ipos/base_com_offset*（依赖运行时 Link mass/COM override 标志）、dof_armature*、dof_frictionloss*	dof_damping 在 Motrix 0.8.2 无公开运行时接口，fail closed；其余 term 不支持。非 portable 模式另有 kp/kd*、geom_friction*、gravity*（均依赖运行时标志）
drake	无	未实现的 reset 项显式报错而非静默 no-op
superdex	无	—
newton	无	—

（subprocess_ipc 基类与 fake 后端同样声明为空。）

Interval DR（运行中按周期施加）

后端	push	body_lin_vel Δ	body_ang_vel Δ	body_force	body_torque
mujoco	✅*	✅*	✅*	✅	✅
mjwarp	✅*	✅*	❌	✅	✅
motrix（portable）	❌	❌	❌	✅*	✅*（需 force+torque 两个运行时标志）
motrix（非 portable）	✅	❌	❌	✅*	❌
drake	❌	❌	❌	✅	❌
isaacgym（mapped）	❌	❌	❌	✅	✅
isaacsim（mapped）	❌	❌	❌	✅	✅
genesis（portable / 非 portable）	❌	❌	❌	✅	✅ / ❌
superdex / newton	❌	❌	❌	❌	❌

（mujoco/mjwarp 的 push 与速度增量依赖实例内 push body id / root qvel 映射是否可用。）

Fixed variants 与 per-env playback

后端	fixed variants	布局	per-env playback
mujoco	✅*（需 mjbatch VariantPack）	same_layout + uniform_public_layout	✅*（有 variant build 时）
mjwarp	✅	两种布局	✅
isaacgym	✅（有 plan 时）	两种布局	✅
isaacsim	✅（mapped + 有 plan 时）	same_layout	未声明
motrix	✅*（有 assignment 时）	same_layout（uniform mesh variants 时 +uniform_public_layout）	✅*（uniform mesh variants 时）
drake	✅	same_layout	✅*（有 variant realization 时）
superdex	✅（有 assignment 时）	same_layout	未声明
genesis	⚠️ 声明缺失：materialization.py 已实现 variant_plan 物化（受 Genesis balanced mapping 约束），但 get_dr_capabilities() 未设置 supports_fixed_variants	—	—
newton	❌	—	—

值得讨论的差距与风险

1. UniLab event terms 与后端支持面的错配：
   • PushBySettingVelocity 依赖 interval body_linear_velocity_delta / body_angular_velocity_delta，目前只有 mujoco（两项）和 mjwarp（仅线速度）声明支持；PhysX 系（isaacgym/isaacsim）、genesis、motrix、drake 全部 fail closed。这类"推扰动"在多数后端是否应以 body_force/impulse 形式降级实现，还是保持 fail closed？
   • RandomizePhysicsSceneGravity（gravity）在 PhysX 系与 genesis 不可用（sim 全局参数）。跨后端任务若想随机化重力，是否需要契约层的语义让步（如 episode 级而非 env 级），还是在任务配置中按后端白名单启用？
2. genesis 的 fixed-variant 声明缺口：物化路径支持 variant plan，但 DR 能力声明为不支持；UniLab 侧 _require_fixed_variant_support()（manager_based_rl_env.py）会在 env 构建时直接拒绝。这是声明遗漏还是有意 fail closed？
3. geom_friction 在 genesis 仅有比例 API：是否需要 unisim 契约增加"相对缩放 vs 绝对值"的语义区分，避免任务层误以为可写绝对摩擦系数？
4. 声明与运行时的落差：当前声明是源码级、自报的；unisim.capabilities 的证据体系区分 source/runtime。是否值得为 DR terms 建立统一的跨后端 effect-test 矩阵（在具备运行时的环境中跑 round-trip 验证），让 UniLab 的能力协商可以引用已验证证据而非纯声明？
5. 基线子集定义：目前事实上的"高覆盖后端"是 mujoco/mjwarp（16 reset + 4~5 interval）。是否应在文档/ADR 中明确一个"跨后端可移植 DR 基线"（例如 body_mass、body_ipos、kp/kd、dof_*、geom_friction、body_force/body_torque），任务配置只承诺基线内的可移植性？

期望结论

• 确认上表与各自后端团队的认知一致（尤其带 * 的条件项与 genesis 的 variant 声明）；
• 就第 1、3、5 点形成决策：哪些差距需要 unisim 契约演进（新 term、语义分级），哪些由 UniLab 任务层按能力声明自适应；
• 如认可第 4 点，另行立项做 DR effect-test 矩阵。

—— 由源码审计自动整理（unisim @ 当前 main），具体实现位置：src/unisim/backend/*/backend.py 中各 get_dr_capabilities()。