架构讨论：per-env 模型间接层的缺失 —— DR manager 与 #1058 600-tool 瓶颈的共同根因

[TATP-233]

背景与问题

起因是一个直觉问题：为什么 UniLab 的 DR 要专门写一个 DomainRandomizationManager，而不是像 mjlab / Isaac Lab 那样直接用 event manager 管理？

带着这个问题对比调研了 mjlab（MuJoCo Warp）和 Isaac Lab（PhysX）后，我们发现 DR manager 的存在和 #1058（SimToolReal 600-tool 吞吐瓶颈）其实是同一个根因的两个症状。把调研结果整理出来，供架构演进参考。

---

1. UniLab 现状：DR manager 与 event manager 是互斥的两代架构

• Legacy provider path：DomainRandomizationManager（src/unilab/dr/manager.py）+ DomainRandomizationProvider，目前仅 Sharpa 手任务家族在用，文档已标注为 legacy。它在 legacy NpEnv 架构里不只是 DR——它就是 reset 本体：provider 产出 ResetPlan（env_ids + qpos/qvel + randomization payload），manager 做 backend 能力协商（get_dr_capabilities()）后调 backend.set_state(...)，再重建观测。plan 是 pickle-safe 的不可变 dataclass，要跨 spawn collector 进程。
• 新路径：Manager-Based 任务通过 Hydra events: terms 做 DR，走 EventManager（迁移自 mjlab v1.6.0 API），ManagerBasedRlEnv 整个覆写 reset()，两条路径互不调用。

所以"为什么不用 event manager"对新任务已经成立——新任务确实在用。但新路径会撞到天花板：RandomizeRigidBodyMass 对 recompute_inertia=True 直接 NotImplementedError，EventManager 明确拒绝直接 model-field 变更。不是 event manager 抽象不行，而是它底下的 backend contract 没有暴露对应能力。

2. mjlab 为什么 event manager 就够：Sim 层吸收了模型字段间接寻址

mjlab 没有 DR manager，DR 全是挂在 EventTermCfg 上的 dr/ 函数。前提是 mujoco_warp 的单 model 多 world 架构：

• Sim.expand_model_fields() 把 model 字段从 stride-0 共享广播 tile 成 (nworld, N) 真实 per-world 内存，零拷贝 torch 直写，CUDA graph 自动重捕获；
• DR 函数用 @requires_model_fields("body_mass", recompute=set_const) 声明字段与重算级别，EventManager 统一收集、统一扩容、apply() 末尾按最强 RecomputeLevel 只重算一次；
• DR 最脏的活（内存扩展、派生量重算、graph 重捕获）被 Sim 层吃掉，manager 层无需特化。

同一个机制支撑了 per-world mesh variants（src/mjlab/entity/variants.py）：所有 variant 的 mesh 合并进一个 canonical MjModel 只 compile 一次，per-world 差异通过 (nworld, ngeom) 的 geom_dataid 间接寻址 + 11 个派生字段 expand 实现；字段数值全部来自每个 variant 源 spec 的独立 compile 再 scatter（compiler-coherent），并有与独立 compile 字节级对照的等价性测试。

3. 这与 #1058 的关系：mjlab 方案本质就是 issue 的「方案 2」

#1058 的三个候选方案对照 mjlab 实践：

• 方案 1（共享公共 compiled data）：mjlab 没有走这条路——stock mjModel 的 ownership/连续 buffer 不适合部分共享，它用"合并进一个 model"回避。可以关闭，requires upstream MuJoCo。
• 方案 2（compiler-coherent variant）：mjlab 证明语义上完全可行，且给出正确性框架。但实现绑定 mujoco_warp 多 world 架构（kernel 用 worldid 索引 (nworld,...) 数组）；stock CPU MuJoCo 的 mjData 直接解引用 mjModel 指针，没有 per-env-row 模型字段间接层，无法直接搬进 MuJoCoUni 的 CPU BatchEnvPool。CPU 路径要等价实现，需上游 MuJoCo 支持 per-world 字段，或引入 warp 类 backend。
• 方案 3（model-affine 调度）：对当前 CPU 路径仍是唯一不依赖上游、立即可行的方案，benchmark 已实测收益上限（K=600 global grouping 93.7ms vs K=1 83.3ms，但收不回 ~18 GiB USS 增量）。

约束匹配度：600 工具只有 3 类 topology，mjlab 的 slot 机制允许 mesh geom 数量不同（padding + dataid=-1），最坏退化为 3 个 template model（600→3 的数量级改善）；assignment 固定 at init，与 tool_id = env_id % 600 完美匹配。

4. Isaac Lab 的对照：异构性放在 USD 层，运行时无感知

• MultiUsdFileCfg：600 个工具 USD 各建 prototype，Sdf.CopySpec 复制 reference arc 到每个 env prim（index % 600）。USD 层源 layer 共享，但 replicate_physics=False 使 PhysX parser 放弃"解析 env_0 一次"的优化，12,288 个 prim 逐个 cooking（Isaac 冷启动 309s vs MuJoCoUni 20s 的主因）。
• cooked collision data 大概率不去重（无代码实锤，多条证据互证：parser 优化被显式排除、instanceable 被强制关闭、Isaac Lab 自己的 ray caster 要手写 mesh 去重、PhysX 官方称共享是调用方责任）——即可能存 12,288 份而非 600 份。mjlab 的 mesh 池方案在内存维度上实际优于 Isaac。
• 运行时 DR：PhysX tensor API（set_masses/set_inertias/set_material_properties）本身就是批量 per-env 写接口，所以 DR 也只是 event term 的一次 tensor setter 调用。

5. 核心判断：缺的是同一个层

	per-env 模型写入的原生能力	结果
mjlab	warp 多 world：字段 expand + 零拷贝直写 + GPU 重算	DR = event term，无需专门 manager
Isaac Lab	PhysX tensor API 批量 per-env 写	DR = event term，无需专门 manager
UniLab（CPU MuJoCo）	没有这个层；每 env row 一个 MjModel 指针，#1058 里甚至 600 个不同 model	DR 必须提升为协议层（能力协商 + pickle plan + 降级）= DR manager

DR manager 的存在和 600-model 瓶颈是同一根因：CPU MuJoCo backend 缺少 per-env/per-world 的模型间接寻址层。 缺它 → 工具只能编译成 600 份完整 model；缺它 → per-env 物理随机化无法写成一次批量 tensor 写，必须有专门组件做能力声明、payload 过滤、跨进程 plan。

6. 建议方向

1. 短期：Task：评估公共模型复用与 model-affine 调度，解决 SimToolReal 600-tool 吞吐瓶颈 #1058 落地方案 3（model-affine 调度），收益已实测、不依赖上游、contract 不变。
2. 中期：把 mjlab 方案 2 的语义设计（合并 template + slot 机制 + 独立 compile 校准派生字段）作为上游 MuJoCo feature request 或 warp backend 的输入。
3. 架构原则：per-world 字段间接/扩容/派生量重算这类能力，应作为 SimBackend 接口的 capability 声明引入（与 DR capabilities 同一条协商路径），backend 不支持则 fail closed，而不是在 env/manager 层探测。
4. 终态：当 backend 暴露批量 per-env 模型字段写能力后，DR 的自然形态就是 mjlab/Isaac 那样的 event term + 批量写字段，DomainRandomizationManager 这个 legacy 协议层可随 Sharpa 家族迁移一起退役——一个问题（Task：评估公共模型复用与 model-affine 调度，解决 SimToolReal 600-tool 吞吐瓶颈 #1058）的解决同时消灭两个技术债。

欢迎讨论：CPU 路径推动上游 per-world 字段支持 vs 引入 warp 类 backend 的取舍，以及方案 3 落地的优先级。

[TATP-233]

补充调研：mjbatch —— CPU 路径上"缺失的那一层"已有可用的第三方实现（附方向决策）

调研了 kevinzakka/mjbatch（CPU 上并行跑数千个 MuJoCo 仿真的库：C++ 线程池、释放 GIL、跨 batch 的数组直访、per-sim 模型参数）。核心结论：本文定位的"per-env 模型字段间接层"，mjbatch 在 stock CPU MuJoCo 上已经完整实现了一套——不改上游、不依赖 warp。 这直接改变三个方案的取舍。

1. 机制对应：mjlab 的三个关键设计，mjbatch 各有等价物

mjlab (mujoco_warp)	mjbatch (stock CPU MuJoCo)
expand_model_fields() 把 model 字段 tile 成 (nworld, N) 真实 per-world 内存，零拷贝直写	Batch.expand(field) 分配 (N, nr, nc) numpy 缓冲，每次物理调用前把该行 memcpy 进每线程一份的 model 副本（batch.h）
@requires_model_fields(..., recompute=set_const) + EventManager 统一按最强 RecomputeLevel 重算一次	Batch.set_const(ids) 逐 env 跑 mj_setConst，并自动把它改过的派生字段全部 expand
与独立 compile 字节级对照的等价性测试	lockstep 测试：expand 后的 batch 与 N 个独立 MjModel/MjData 逐步仿真结果一致（test_batch.py）

内存特性与本文判断直接相关：model 副本是每线程一份、不是每 env 一份（只有首次 expand 才分配）；每个 env 常驻的只有 mjSTATE_INTEGRATION 向量。即"内存随线程数而非 env 数扩展"——与 600 份独立 MjModel 的 ~18 GiB USS 正好相反。

2. 这意味着什么

"终态"不必等上游。 本文判断 DR 的自然形态是 event term + 批量 per-env 字段写，但认为 CPU 路径要等上游 per-world 字段或 warp backend。以 mjbatch 为 backend，现在就能写：

batch.expand("body_mass")[env_ids, body_id] *= u
batch.set_const(env_ids)  # subtree_mass / dof_M0 等派生量逐 env 重算

RandomizeRigidBodyMass(recompute_inertia=True) 目前直接 NotImplementedError 的天花板就此消失；per-env gravity / timestep / integrator / friction 同理（均有测试覆盖）。EventManager 对 model-field 变更的拒绝可以变成正常的 capability 协商。

capability 契约有了参考实现。 建议 3 要的"per-world 字段能力作为 SimBackend capability 声明、fail closed"，mjbatch 的 API 形态恰好是最小集：expand 对不支持的字段明确报错、set_const 做派生重算、asset 字段与 sleep 显式拒绝。

对方案 2 有个意外的利好。 mjbatch 禁止 expand 的是 mesh_ / hfield_ / tex_ 等 asset 数据本体，但 geom_dataid 是普通 int 字段，可以直接 expand。mjlab variants 的整套语义——合并 canonical model + per-env geom_dataid 间接寻址 + 派生字段由各 variant 独立 compile 后 scatter 进 expand 缓冲——运行时机制在 mjbatch 上已经全部现成；合并后的 mesh 池在线程间只读共享。剩余工作集中在 mjSpec 合并/校准层，不在运行时。

3. 代价与边界（如实说明）

• 非真零拷贝：每次物理调用需把 expanded 字段逐 env memcpy 进线程的 model，开销随 expanded 字段数线性增长。DR 只在 reset 写字段时可忽略；每步大量改字段的场景逊于 warp 的 (nworld, N) 直写。
• 单拓扑：一个 Batch 一个模板 model；拓扑不同须分 batch 或先合并 canonical model，没有现成的 slot/padding 机制。
• numpy/CPU 世界：缓冲是稳定 numpy 视图，torch.from_numpy 可零拷贝桥接；无 GPU 路径；不支持 sleep（fail closed）。
• 多进程 collector 下 Batch 不能跨 spawn 传递——但 DR 下沉为 backend 能力后本就不再需要跨进程 pickle plan，与本文方向一致。

4. 方向决策更新

基于以上，三个候选方案重新定夺：

• 方案 1（共享公共 compiled data）：确认放弃。 依赖上游 MuJoCo ownership 改造；mjbatch 证明同等语义可在 stock MuJoCo 外部实现，此路不再必要。
• 方案 3（model-affine 调度）：确认放弃。 收益上限已实测收不回内存增量；既然方案 2 在 CPU 路径的运行时载体已经存在，过渡方案不再值得投入。
• 方案 2（compiler-coherent variant）：作为长期方案执行。 落地形态：mjSpec 层做 3 类 topology 的 canonical model 合并 + variant 独立 compile 校准派生字段；运行时以 mjbatch 为 CPU backend，geom_dataid 及派生字段走 expand 缓冲 scatter；DR 同步迁移为 event term + 批量字段写，DomainRandomizationManager 随 Sharpa 家族迁移一并退役。

[TATP-233]

现状更新：per-env 模型间接层已在 MuJoCo 与 MJWarp 后端落地，legacy DR manager 已退役

结论先更新一下：这个讨论定位的“backend 缺少 per-env model-field / model-identity indirection”已经不是提案状态。UniSim 的 MuJoCo CPU 与 MJWarp 两个 adapter 都已经落地，UniLab 也完成了消费侧收口。设计目标保持不变，并且现在可以明确写成两条硬约束：

• no legacy mode：Manager-Based runtime 是唯一运行路径，不允许 legacy EnvCfg -> NpEnv factory / compatibility seam 与它共存；
• no DR manager：DR 的唯一生命周期是 EventManager terms + UniSim capability 协商 + curated payload，不允许再引入第二套 manager/provider 协议层。

1. MuJoCo CPU 后端

• 执行器已切换到 mjbatch-uni（feat(mujoco): switch the mujoco backend executor to the mjbatch fork unilabsim/unisim#64；roadmap roadmap: unisim mujoco 后端批执行器从 mujoco-uni-runtime 替换为 mjbatch #1552 / feat: mujoco 后端依赖切换 mjbatch + 配置清理 (roadmap #1552 child #6) #1553，底层 roadmap Roadmap: per-env model variants and ModelWrite capability contract unilabsim/mjbatch_uni#3）。
• reset-time curated model fields 直接写入 Batch.expand(field) 的 per-env 行，随后对 selected rows 做一次 set_const() 重算派生常量；mutable model 副本按 worker thread 数而不是 env 数扩展。
• fixed model variants：每个 variant 先独立 compile 作为数值/default oracle，layout 校验后交给 mjbatch VariantPack 合并 canonical executor；geom_dataid 做 per-env pooled mesh 选择，运行时 reset 写入复用同一套 expanded model-field views；get_reset_term_default() 返回 canonical/per-world 默认表；playback 可按 env 解析独立编译的 visual oracle（feat: implement per-env fixed model variants unilabsim/unisim#70，playback 修复 fix(mujoco): preserve visual playback models unilabsim/unisim#74）。

2. MJWarp 后端

• 构造期冷路径把可随机化 model fields、派生字段与 opt.gravity 从共享数组替换成 (nworld, ...) per-world 数组，并在第一次 forward / CUDA graph capture 之前完成；之后的 DR 写入是对固定地址数组的 in-place upload，保持 graph-safe（feat: implement per-env fixed model variants unilabsim/unisim#70 / Sim：G1 WBT 迁移到 MotrixSim #75）。
• fixed variants：每个 MJCF 源独立 compile 做 oracle，合并 mesh/material 到 canonical model，安装 per-world geom_dataid / geom_matid 与 11 个 mesh-dependent fields，再刷新 compiler-derived constants（feat: implement per-env fixed model variants unilabsim/unisim#70）。
• per-env gravity、body force/torque 与 per-substep dynamic wrench 已补齐，并与 MuJoCo 后端保持同一公开契约和生命周期语义（补齐 mjwarp 的逐环境重力设置与跨后端 body wrench 控制 unilabsim/unisim#71 / Sim：G1 WBT 迁移到 MotrixSim #75；CPU 侧配套 step() split-substep callback（mj_step1/mj_step2 分割点）+ 位置/速度级传感器增量拷出 unilabsim/mjbatch_uni#28 / refactor: move env base modules to unilab/base #29）。

3. UniLab 消费侧与架构收口

• env.fixed_model_variants 只声明任务 catalog / final assignment；Manager factory 在冷路径生成 UniSim FixedVariantPlan，backend 构造后 identity 不可变，reset event 不改变 identity。所有权边界记录在 ADR-0010。
• reset DR 的唯一路径是 EventManager terms → ResetStateTransaction → 一次 SimBackend.set_state(..., randomization=...)；interval DR 走 IntervalRandomizationPlan。backend 未声明的 capability 一律 fail closed，不按 backend 名称、可选包 import 或异常类型降级推断。
• DomainRandomizationManager / provider protocol、unilab.dr namespace 与 NpEnv hooks 已物理删除；legacy task-factory / compatibility seam 也已删除，registry closeout 禁止 legacy factory 与 canonical Manager-Based runtime 共存（Retire legacy DomainRandomization provider protocol #1567 / feat: complete per-env fixed model variant roadmap #1568，chore: prune redundant defensive tests and remove the legacy task-factory seam #1572 / chore: prune redundant tests and remove legacy task-factory seam #1573）。
• Representative SimToolReal fixed-tool workload 已在 CPU 与 MJWarp 上验证（Integrate SimToolReal fixed tool variants #1566 / feat: complete per-env fixed model variant roadmap #1568）。
• 版本收口：UniLab 1.3.0 依赖 unisim-core>=1.4.0 + mjbatch-uni~=0.2.1（deps: unisim-core 1.4.0 and mjbatch-uni 0.2.1 #1574 / release: unilab 1.3.0 #1575；unisim v1.4.0、mjbatch_uni#30）。

4. 仍然 fail closed 的边界

这些是显式契约边界，不是回退到 legacy path 的理由：

• variant layout 只承诺 same_layout / uniform_public_layout；无法投影到统一 public state/action/sensor layout 的异构 topology 报错。
• MJWarp 的 reset-time geom_size 仅支持 primitive geometry；mesh / hfield / SDF resize 不支持。
• mass / inertia 写入后的派生常量由 backend set_const 语义负责；randomize_rigid_body_mass(recompute_inertia=True) 的“从几何重推导 inertia tensor”语义仍未进入 payload contract，需要显式设为 false，或使用 randomize_body_mass_inertia。
• MuJoCo native executor 不支持 Windows / musllinux；MJWarp 需要 CUDA；跨后端不承诺 bit-exact。

关联索引

UniLab

• 根因与工作负载：Task：评估公共模型复用与 model-affine 调度，解决 SimToolReal 600-tool 吞吐瓶颈 #1058（已由 roadmap roadmap：跨 mjbatch、UniSim 与 UniLab 实现 per-env 模型字段与工具变体 #1563 接管并完成落地）
• MuJoCo executor 迁移：roadmap: unisim mujoco 后端批执行器从 mujoco-uni-runtime 替换为 mjbatch #1552 → feat: mujoco 后端依赖切换 mjbatch + 配置清理 (roadmap #1552 child #6) #1553；feat: mujoco 后端适配层切换到 mjbatch Batch (roadmap #1552 child #4) unilabsim/unisim#58 → feat(mujoco): switch the mujoco backend executor to the mjbatch fork unilabsim/unisim#64
• per-env model / fixed variant roadmap：roadmap：跨 mjbatch、UniSim 与 UniLab 实现 per-env 模型字段与工具变体 #1563；children Define task-owned fixed variant config and cross-repository ADR #1564 / Consume per-env model fields in Manager-Based reset transaction #1565 / Integrate SimToolReal fixed tool variants #1566 / Retire legacy DomainRandomization provider protocol #1567；完成 PR feat: complete per-env fixed model variant roadmap #1568
• legacy seam 清理：chore: prune redundant defensive tests and remove the legacy task-factory seam #1572 → chore: prune redundant tests and remove legacy task-factory seam #1573
• 依赖与发布：deps: unisim-core 1.4.0 and mjbatch-uni 0.2.1 #1574、release: unilab 1.3.0 #1575
• 架构决策：ADR-0010

unilabsim/unisim

• mjbatch executor：Docs：README 里面没有 G1 wbt 任务的训练指南 #58 → Sim：MuJoCo/Motrxsim 域随机化 #61 / Fix Fastsac+G1  #63 / fix G1+SAC  #64
• fixed variant contract 与两个 adapter：fix: restore G1 SAC locomotion training performance #66 / fix: restore G1 SAC locomotion training performance #67 / style: ruff format joystick_sac.py #68 → refactor: share logger lifecycle without changing wandb semantics #70
• MJWarp per-env gravity + cross-backend wrench：Demo：Leap Hand 真机演示 #71 → Sim：G1 WBT 迁移到 MotrixSim #75；playback 修复 Data：G1 WBT 两个新数据集交付 #74
• releases：v1.3.0、v1.4.0

unilabsim/mjbatch_uni

• per-env model roadmap：fix go2 reward #3；children fix go1 reward #4 / Dev/mlx rl #5 / Dev/g1 #6 / Dev/mujoco mlx #7；PRs Dev/native process #8 / Dev/native process #9 / Dev/compatibility #10 / Dev/compatibility #11 / 测了一下linux host numpy 做 mlp, 真是失败的尝试. 得出结论,在linux上这样搞太差了, 不要再幻想了 #12；设计消融 fix install #13 / Dev/gpu buffer #17
• API ablation 与发布：Update the AllegroInhandRotation Code According to the Updated Backend Code. #22 / Dev/sac g1 #23、support domain randomization(mass, com, ex force) in motrixsim #26 / refactor: move base modules from unilab/envs to unilab/base #27
• split-substep callback：move push_function random_set to np_env #28 → refactor: move env base modules to unilab/base #29；release perf: remove cpu_buffer intermediate copy in write_weights() #30

因此，这个讨论的终态判断可以更新为：event manager + backend capability + curated per-env payload 已经在两个 production backends 兑现；DomainRandomizationManager 与 legacy mode 不再是“待退役项”，而是已经删除。后续扩展应继续走 UniSim SimBackend capability + adapter 实现，不再恢复任何兼容双路径。