跳转至

CoDA PhysicalArtiObj Reproduction and Studio Bridge

文档类型：Implementation Details
架构权威：Physics Studio Architecture 原生结果名称：CoDA-PhysicalArtiObj / native reproduction
Studio 结果名称：CoDA-PhysicalArtiObj / ArtHOI Studio benchmark

1. 两条独立路径

CoDA 作者提供的 submodules/CoDA 包含完整 articulated task、observation、 reward、network、PPO/GAE、checkpoint 和 player。项目不再在 pipeline/physics/backends/coda.py 重写这些算法。

flowchart LR
  A["Author ARCTIC input"] --> N["Official MimicArti task + trainer"]
  N --> NR["Native reproduction result"]

  C["case.json + result.pt"] --> D["thin backend + author config"]
  D --> T["Author MimicArti Task / VecEnv / trainer / player"]
  D --> B["opt-in CoDA Studio task bridge"]
  B --> T
  B --> H["shared scene / reference / contact helpers"]
  H --> T
  T --> X["author rollout lifecycle"]
  X --> Q["shared common recorder"]
  Q --> R["common_rollout.npz"]
  R --> V["Common evaluator / renderer / Viser"]

Native reproduction 证明作者代码可运行；Studio benchmark 比较统一 canonical input。 两条路径使用不同结果名称、目录和 run record，不能共享 checkpoint 或结果行。

2. Source boundary

pipeline/physics/
  canonical input / shared scene-reference-contact-recorder helpers
  evaluator / renderer

pipeline/physics/backends/coda.py
  lazy import / explicit opt-in task registration / return validation

submodules/CoDA/
  author Task / VecEnv / manager / simulator lifecycle
  author network / PPO / checkpoint / player
  opt-in Studio bridge for shared articulated state

主仓库 backend 不定义 network、loss、optimizer、rollout buffer 或 trainer。Worker bootstrap 传入 canonical/config descriptors 和共享 helper；不传预建 live env。 作者 Task/VecEnv factory 仍在原本的 task-construction 时点创建并拥有唯一 simulator， opt-in bridge 只在既有 manager lifecycle 中调用共享 helper。Official entrypoint、 config 和 task registration 完全不读取 Studio flag。

studio_vendor_manifest.json 记录作者提供 ZIP 解压出的 PhysicalArtiObj delivery， 不借用其他挂载副本或伪造 Git commit。scripts/physics/verification/coda_vendor_snapshot.py 先校验 archive SHA-256，再逐字节校验 ZIP 中全部 physhoi 文件。唯一允许修改的作者 文件是 parse_task.py 的显式 Studio task 分派；唯一新增文件是四个 physhoi/studio/* bridge 文件。MimicArti 路径不会 import physhoi.studio；只有显式 task 名 MimicArtiStudio 才在 parse_task 内 lazy import bridge。

这份作者 delivery 目前没有可公开 clone 的 remote，也未登记为 Git submodule。因此公开发布前 必须取得作者允许的 source URL 或可分发 archive，并把获取步骤固定下来；在此之前， submodules/CoDA 是明确的外部 provisioned dependency，不能声称 fresh clone 可直接运行 CoDA。

3. Gate A：native strict reproduction

权威入口仍是作者命令：

bash mimicgen_run_ours.sh

验收：

  • 作者指定 ARCTIC/CoDA motion、humanoid XML、object asset 和 table 可读取；
  • MimicArti 使用作者 4096 env、60 Hz、horizon、GAE、minibatch、mini-epochs；
  • observation、153-D human action 和 reference-centered residual PD 未改变；
  • articulation、interaction graph、fingertip-contact reward 与 termination 未改变；
  • checkpoint save/reload、resume 和 deterministic player 可运行；
  • 作者 TensorBoard/event log 完整保留；
  • pinned upstream official config byte-identical，official entrypoint 不读取 Studio flag；独立 Studio config 显式写 studio.enabled: true，缺失或 false 直接拒绝 Studio dispatch。

只允许不改变 tensor、reward、action、dynamics、optimizer 或 schedule 的运行兼容补丁。 作者的原生 q clamp、contact 判定和 floating/table protocol 即使不适合 Studio，也不能在 Gate A 静默修改。

4. Gate B：minimal Studio bridge

Studio input 只有：

case.json
result.pt
contact_labels.npz  # path is stored in case.json

Shared Phase 1 helpers 负责：

  • 在作者已拥有的 simulator 中加载 complete \(J\)-joint articulated object、ground 和 support geometry；
  • 复用作者 asset/build/reset/step/tensor-refresh 生命周期，提供 named object state 和 contact telemetry；
  • passive/unactuated object joints；
  • canonical reference materialization，以及 fresh eval 的 common recording。

CoDA Studio bridge 只负责：

  1. 在作者 MimicArti manager lifecycle 中调用上述 helper，并将 shared named tensors 映射回作者 task/trainer 接口；
  2. 保留作者 native human/fingertip/BPS/contact computation；root thin input adapter 将 canonical hand2 labels 按左右手确定性广播为具名十 fingertip reference，再传给作者 task；
  3. 在 simulation/reset/reference/recording 中保留完整 \(J\) 个 object joint；当前 CoDA 作者 reward/observation 只接受一个 supervised target joint，因此多 active-target case 必须显式拒绝，而不能伪造为多目标 CoDA。

Common recorder 属于 Studio evaluation boundary；opt-in bridge 只在作者 reset/step 边界通知 recorder，作者 player 不读取 common rollout、evaluator 或 renderer。

所有 \(J\) 个 object joints 都在 simulation、reset initialization、checkpoint contract 和 common rollout 中保留；作者 single-joint observation 只投影 supervised joint。Inactive joints 不 actuation、不锁定、不每帧写回 reference；被人体误撞后可以运动，也不参与 reward 或 termination。Common evaluator 报告 drift metric，renderer/Viser 显示实际运动， 但该值不参与二元 Success/Fail。

Network、value head、normalizer、rollout buffer、GAE、PPO loss、optimizer、scheduler、 curriculum、reference initialization、reset/termination 和 checkpoint 必须继续运行作者 实现。Morphology、contact representation 或 observation dimension 改变时必须 fresh train；official checkpoint 只属于 Gate A。

Phase 1 不把 MimicArti manager 拆成纯函数，也不由 standalone root IsaacEnv 接管 作者 Task/VecEnv/simulator。该 extraction 属于可选 Phase 2，需要独立设计与 parity 验收，不是当前完成门槛。

5. Gate C：trainer-level parity

先冻结同一组 captured raw tensors。对 \(J=1\) Studio case 检查：

Check Requirement
Non-articulated observation slices exact
Unchanged reward components exact
Action distribution / target exact
Normalizer update exact
Return / GAE / PPO loss exact
Minibatch and mini-epoch count exact
Optimizer / scheduler update exact
Reset / termination / history exact
Save / fresh reload / resume iteration exact

完全相同路径要求 bitwise match；经过明确 canonical mapping 的浮点张量默认 atol <= 1e-6, rtol <= 1e-6。Strict path 保留 native fingertip/contact/IG； dynamic-\(J\) object reward 单独做 deterministic regression。若另做 CoDA-Studio-52，其 62→52+tip-sites mapping 是 disclosed representation adaptation， 不能伪装成 articulated-object-only parity。

Hand2→ten-tip mapping/version/digest 必须冻结。Parity 使用同一个映射后的 (T, 10) batch 比较 official task 与 Studio bridge 的 contact/IG observation、reward 和 gradient； 这些作者计算必须 exact。Studio 不声称映射后的 reference 与 native ARCTIC ten-fingertip annotation 数值相同，official reproduction 也不使用该 mapping。

对 \(J=0/1/2\) 另外检查：

  • canonical joint name/order 与 observation dimension；
  • active-only reward reduction；
  • inactive joint 保持 passive 而非 frozen；
  • checkpoint 严格记录并校验 \(J\)、joint names/order、active names、contact-link names/order 和 observation size；
  • mismatch checkpoint 直接失败。

6. Gate D：train, reload and common evaluation

Format pilot 运行 5 个作者 outer iterations。每个 iteration 必须收集完整 native horizon， 执行作者 GAE、minibatch 和全部 mini-epochs；不是五个 env.step() 或五个 optimizer.step()。除了 outer-iteration 上限与强制保存一次 author-native checkpoint set，作者 config 不改。

Fresh evaluation 使用新 Python 进程、num_envs=1。作者 criterion 的第一局是 warm-up， 因此 player 顺序运行两局：第一局不录制，第二局从 frame 0 开始录制一个连续 episode：

train/
  checkpoints/
  tensorboard/events.out.tfevents.*
  <author resumable state>
  run_record.json

eval/
  humanoid.xml
  common_rollout.npz
  evaluation.json
  run_record.json
  replay.mp4

Evaluation 不保存 native rollout、native input copy、object config、renderer sidecar 或 method-specific simulator asset。common_rollout.npz 保存完整 \(J\) 个 q/q-reference； common evaluator 只读取 case.json + common_rollout.npz + evaluation config，输出一个 Success/Fail 和诊断 failure reason。Renderer/Viser 的动态状态也只来自 common rollout。

5-iteration pilot 只验证 author trainer、checkpoint/reload、train log 和 common downstream 闭环，不要求 reward 上升或 task Success。

7. Completion gates

  • Gate A official reproduction 未被 Studio commit 改变；
  • thin root backend 不含训练算法；
  • Studio bridge 的每项修改都能归因到 shared scene/reference/contact/recorder boundary 或 articulated-object state；
  • 作者 Task/VecEnv/manager/simulator lifecycle 与完整 trainer/player 保持；
  • J=1 trainer-level parity 通过；
  • J=0/1/2、active/inactive、checkpoint mismatch tests 通过；
  • 5 native-iteration train、author TensorBoard、checkpoint 和 fresh reload 通过；
  • single-env common rollout、binary evaluation、common render 和 keyframes 通过；
  • 至少三个预注册 D3D-HOI canonical cases 完成 formal matched-budget training；
  • crash/timeout/missing rollout 保留为 Fail，所有数字可追溯到 run record；
  • 当前 generic trainer 输出保持 interface_sanity_only，不进入表格或网站成功率。

完成 CoDA fidelity anchor 后，再以相同规则迁移 InterMimic、RePHO、PHC-X 和 ours。