Trace と replay

simulation の再現性を調べるには、最終 pose だけでなく、入力がいつ見え、sensor がいつ取得され、controller が何を出し、actuator がいつ適用したかを記録する必要があります。 Fibril Simulation の semantic trace はこれらの boundary を MCAP に保存します。

Trace を有効にする

Manifest から trace を常時有効にする場合は trace.enabled を指定します。

trace:
  enabled: true

CLI の一回の run だけ保存する場合は --trace を使えます。 この option を指定した run では Plan の trace policy も有効化されます。

fibril_sim run simulation.yaml --steps 1000 --trace run.mcap

Trace が分けて記録するもの

Device では raw source、Device semantics 適用後の acquired value、controller-visible な delivered value を分けます。 actuation では controller command、transport release、virtual driver 適用後の actuator application、post-physics actuator force を分けます。

post-physics physical evidence として qpos / qvel / sensordata に加えて、body world pose、generalized actuator force、generalized constraint force を保持します。 contact は geom / flex identity と geometry だけでなく、solver constraint への参加状態、full contact frame、contact-frame wrench、adhesion も記録します。 このため「contact record が存在する」と「実際に constraint force を伝えている」を分けて調べられます。

この区別により、同じ最終 state のずれでも sensor model、controller、transport、driver、plant のどこから差が始まったかを追えます。

trace を有効にしていない通常 run では、camera や LiDAR payload を trace 用に serialize する cost は発生しません。

Persisted trace を問い合わせる

一つの failing run の中で何が起きたかを見る場合、全 frame を独自 script へ展開せず trace info / trace query を使えます。

fibril_sim trace info run.mcap --json

trace info は frame summary と一緒に、MCAP metadata に保存された model / compiled-model / Manifest / parameter-set hash、resolved asset hash、MuJoCo version、extension、episode seed も返します。

failure の前後だけに時間窓を絞り、named signal と contact を同じ timeline で確認できます。

fibril_sim trace query run.mcap \
  --manifest simulation.yaml \
  --from 4.0 \
  --to 6.0 \
  --signal joint:arm_joint.position \
  --signal joint:arm_joint.qfrc_constraint \
  --signal body:payload.position \
  --signal actuator:arm.force \
  --contact payload \
  --active-contacts-only \
  --json

actuator: selector には Fibril actuator endpoint ID を指定します。 query の selector と option は CLI reference を参照してください。

Plan の semantic name 解決が不要な causal record は Manifest なしでも問い合わせられます。

fibril_sim trace query run.mcap \
  --from 4.0 \
  --to 6.0 \
  --input motor/command \
  --device front_lrf \
  --event attachment \
  --domain competition \
  --json

これにより committed input、Device acquisition / delivery、semantic event、Domain execution を同じ boundary timeline で追えます。

ROS live simulation の trace

generic fibril_simulation node では trace_path parameter を non-empty にすると trace policy が有効になり、その path へ MCAP trace を保存します。

trace_path:=/tmp/failing-run.mcap

mutable SimulationInstance と mjData は SimulationHost の worker thread が単独所有します。 trace frame は completed boundary から immutable data として搬出し、MCAP write は ROS frontend 側で行います。 debug のために ROS callback から active MuJoCo state を直接読む経路は追加しません。

Recorded ExternalInput を replay する

fibril_sim replay は trace に記録された ExternalInput と commit tick を新しい Instance へ投入し、同じ step 数を実行して expected trace と比較します。 Instance の episode seed も trace に記録された値を使うため、Manifest の default seed と異なる recording でも同じ run-local randomness を再現します。

fibril_sim replay simulation.yaml \
  --trace run.mcap \
  --manifest-profile full \
  --scenario scenario.yaml \
  --scope state \
  --tolerance 1e-9

--scope は比較範囲を選びます。

• semantic：causal metadata と非数値 semantic value を比較します。
• actuation：semantic に actuator command と application の比較を加えます。
• state：post-physics の numerical state まで比較します。

--tolerance は numerical comparison の absolute tolerance です。

Replay の結果

equivalent であれば replay した frame 数が表示されます。 divergence が見つかった場合は非ゼロ終了し、最初に差が出た frame と field を報告します。

automation から使う場合は --json を指定します。

fibril_sim replay simulation.yaml --trace run.mcap --scope state --tolerance 1e-9 --json

同じ入力を再生しても、異なる build、model、parameter、MuJoCo version なら数値結果が一致しない場合があります。 原因調査では trace comparison と Plan provenance をセットで確認します。

Trace 同士を比較する

既に二つの trace がある場合は trace compare で直接比較できます。

fibril_sim trace compare reference.mcap candidate.mcap \
  --scope state \
  --tolerance 1e-9

parameter variant を比較する場合は Parameter Experiments、実測から parameter を推定する場合は Calibration を使います。