Manager-Based collector 性能上限：静态数据流与整阶段融合的可借鉴方向

[TATP-233]

结论先行

UniLab 的社区兼容 Manager-Based API 已在 #1042 下形成稳定 authoring contract；#1292 又确认，sac/g1_motion_tracking 使用 mjwarp 时，瓶颈已从物理转移到 host NumPy manager 数值层和 reset：

phase（8192 envs）	mjwarp
env step	约 64.0 ms
update_state	约 29.8 ms（46.6%）
reset_done	约 15.1 ms（23.6%）

#1293–#1296 已完成逐 term profiling、有限值检查采样、reset row-scoped getter 和纯 NumPy 临时数组消除。它们解决了明确的局部浪费，Motrix 因 backend row-scoped 边界获得显著收益；但 mujoco/mjwarp 的 update_state 端到端变化已接近单窗口噪声带，继续逐个修改 NumPy 表达式很难突破当前上限。

本文讨论是否可从另一套 MotrixLab Manager API 设计中，只借鉴内部执行模型：

1. 静态 simulator query plan；
2. 固定 workspace/data layout；
3. observation/reward/metric 直接写预分配输出；
4. 对纯数值计算簇做整阶段 fused kernel。

本文不建议替换 UniLab 公共 Manager-Based API，不授权重启 Numba 支持路径，也不改变 NpEnv、runner、IPC、checkpoint 或 backend lifecycle。

相关记录：

• #1042：社区通用 Manager-Based API roadmap
• #1292：Manager-Based API 下 Numba/collector 后处理评估
• #1293：逐 term profiling
• #932：历史 Numba 路线完整复盘
• PR #929：自动 term-plan/fusion 跨硬件复测
• Discussion #1289：UniLab 与 mjlab Manager-Based API 对比

当前数据的指向

#1293 在 8192 envs、mjwarp 上归属到 update_state 的主要部分为：

类别	ms/vector-step
reward terms	5.68
termination terms	4.99
observation getter term	0.93
observation per-term postprocess	2.00
observation group concat/postprocess	1.14
已归属合计	约 14.7

单个最大 term 是 termination/anchor_pos，但 #1296 证明其大头来自首次 robot-state gather/cache refresh，而不是 termination 数学本身。后续应把 getter、共享派生量、输出装配和多个 consumer 看作一个数据流，而不只按 term 名逐个优化。

“未归属”的约一半时间可能包含 command 更新、manager 编排、observation mapping、logging/reduction、state replacement 或未埋点的派生计算，不能直接当成可消除开销；选方案前仍需更细的临时 profiling。

方向一：冷路径 StateReadPlan

MotrixLab 设计要求 term 先声明 simulator 输入。UniLab 不需要新增公开 sim_queries 配置，但可在现有 EntityScene/backend facade 上建立内部读取计划：

manager/task declarations
  -> cold-path dependency binding
  -> StateReadPlan(full-step, reset-rows)
  -> backend/entity views
  -> shared derived state
  -> termination/reward/observation

计划提前固定实际需要的 root/joint/body/sensor 字段、selector/列顺序、full/reset-row 读取方式、多 term 共用的 getter/派生状态、可合并的跨语言 getter，以及 mutation 后需要失效的具体缓存。

UniLab 已有 update-phase _EntityStateReadCache；这里建议增加的是冷路径依赖计划与 bulk/row 布局，不是第二套 scene/backend abstraction。若需要新的 SimBackend bulk getter 或 mutation/version contract，必须拆成独立 backend child。

方向二：预分配 ObservationAssemblyPlan

当前 ObservationManager.compute_group() 的常见路径是：

term batch array -> copy -> noise/clip/scale -> 临时 dict -> concatenate -> group check

manager 构造时可计算每个 term 的最终 output slice，并分配 group buffer：

term result -> copy into group_output[:, term_slice] -> in-place postprocess -> publish

这不改变现有 func + params -> np.ndarray contract，却可减少 term copy、临时 dict/list 和最终 concatenate。delay/history/noise、non-concatenated group 与 reset-row 分别生成冷路径 plan，不能在热路径动态探测。

需要先验证 NpEnvState observation 引用生命周期；若 consumer 要求上一 transition 在下一 step 后仍不变，应使用 ping-pong buffer。

方向三：统一 WorkspacePlan

MotrixLab 的固定字段可抽象为四类内部存储：

类型	UniLab 含义
per-env	第一维为 num_envs 的运行期状态
shared	motion clip、查表数据、固定参数
scratch	每步复用且不发布的工作区
metric/output	固定 reward、termination、observation、diagnostic slot

无需引入新 decorator 或公共 term 类型；只在 init/warmup 完成 shape/dtype 校验、分配和 first-touch。它本身未必带来明显 e2e 收益，但可为直接输出和融合实验提供稳定布局。

方向四：整阶段 fused kernel island

若前三项仍不能突破 mjwarp 上约 30 ms 的 update_state，唯一值得重新评估的编译方向不是逐 term njit，而是一个共享输入的纯数值计算簇：

motion/reference + robot body/joint state + action
  -> relative transforms
  -> anchor termination
  -> body pos/ori/linvel/angvel rewards
  -> actor/critic observation slices

一个 kernel 在同一 outer-env loop 中直接写 termination mask、reward slots/final reward、actor/critic observation slices 和必要 metrics，从而减少 Python dispatch、中间 ndarray、重复内存遍历和派生量重算。

按 #1293 的旧口径，上述 term/postprocess 合计约 14.7 ms；即使只减少一半，也可能比继续优化单 term 更接近可见 collector 收益。这个数字只是 POC 上限估计，不是收益承诺。

风险与 #932 的约束

#932 已证明 standalone kernel 收益不等于 collector e2e；task-specific 双实现、固定 term order、parity 与支持矩阵成本很高；Numba worker 会和 physics/Torch/replay 线程池竞争；自动 plan/fusion 对 task、规模、线程和 NUMA placement 敏感；cold JIT、cache、依赖和 CI 都有永久成本。

MotrixLab 设计可能改变结论的唯一前提，是它从源头把 term 数据/访问限制为静态 kernel-safe 结构，减少通用 routing 和自动分析失败。但如果 UniLab 最终仍维护 vectorized NumPy 与 compiled scalar 两份数学，这个优势就不存在，应停止实验。

明确不借鉴

• 不修改 Roadmap: 将 UniLab 迁移为社区通用的 Manager-Based API #1042 固定的 manager 模块、func + params、function/class term 和批量 NumPy contract。
• 不把 @kernel_data、per-lane context 或 njit 暴露给 task author。
• 不引入第二套 Python task config、term order 或 reward 默认值。
• 不让 term 接触 backend 私有 model/data。
• 不用 compiled path 处理 backend set_state、Motrix Rust 边界、physics、RNG 或 reset lifecycle。
• 不恢复旧 Roadmap: 在 G1 walk 与 motion tracking 跑通结构化、自动融合的 NumPy/Numba term #918/feat: package issue 918 Numba roadmap independently #929 代码作为默认起点。
• 不在一个 issue 中同时改公共 manager contract、backend capability、production lifecycle 和 JIT runtime。

建议验证顺序

A. 补齐热点归属（临时，只测不改）

测量 command compute/post_compute、observation mapping、logging/reduction、state replacement、Entity cache hit/miss/getter 字节量、NumPy allocation 和内存带宽。埋点产出结论后删除。

B. ObservationAssemblyPlan（低风险独立 child）

只做预分配 group layout 和 slice assembly；不改 term API、数学、noise/history 或 env lifecycle。验证三后端 A/B、observation lifetime、partial reset 与数值 parity。

C. StateReadPlan（独立 owner child）

先只消费现有 public entity/backend surface；只有数据证明需要 bulk/row getter 时，另提 SimBackend contract issue。

D. Fused kernel POC（实验、非 production）

• 只覆盖 sac/g1_motion_tracking 一个纯数值簇；
• 不接 owner YAML、registry、runner 或 IPC；
• 不给 main 增加普通依赖或正式支持路径；
• serial 与受控线程分别测；
• 输入为已物化 NumPy state frame，排除 reset/backend/RNG；
• 与现有 manager 逐输出 parity；
• 报告 8192 及更大规模、cold/warm compile、RSS、CPU utilization、线程、NUMA/affinity；
• 最终运行 mujoco/motrix/mjwarp 三后端同机 collector e2e。

对于需要新依赖或长期第二执行路径的方案，建议预先采用更高 gate，例如：两台不同 CPU 上 mjwarp collector e2e 稳定提升至少 15%，mujoco/motrix 无统计显著回退，且没有第二份 term 数学。阈值应由 maintainer 在 POC 前确认；未达到即删除实验。

规模与永久维护成本

这不是一个 implementation issue。A/B/C/D 必须分别只有一个主要结果：

• A 永久维护成本为零；
• B 只维护 observation layout/buffer lifecycle；
• C 维护 query binding、cache invalidation 和 backend conformance；
• D 未达 gate 后全部删除；若晋升 production，必须单独接受 compiler/runtime 依赖、cache、thread budget、多硬件 benchmark、parity 和 CI 成本。

希望讨论的问题

1. perf(profiling): motion tracking update_state/reset_done 逐 term profiling（#1292 杠杆 1） #1293 未归属时间应先补哪些边界？
2. 是否同意先做不改变公共 API 的 ObservationAssemblyPlan？
3. StateReadPlan 应只留在 EntityScene 内部，还是需要 public bulk-view contract？
4. 整阶段 fused kernel 相对 Roadmap: 在 G1 walk 与 motion tracking 跑通结构化、自动融合的 NumPy/Numba term #918/feat: package issue 918 Numba roadmap independently #929 是否提供了足够新的实验变量？
5. 什么 e2e gate 足以覆盖新 execution path 的长期成本？
6. 是否接受“未达预设 gate 即完整删除，不保留默认关闭路径”？

本 Discussion 只用于选择下一项评估工作；批准讨论本身不授权公共 contract、backend capability 或 production compiled execution path。