CLI リファレンス
fibril_sim_cli は fibril_sim command を提供します。simulation の操作は fibril_sim <command>、model から artifact を作る操作は fibril_sim model <command> です。
human-readable output と automation 向けの versioned JSON output を使い分けられます。
Machine-readable output の契約
--json がある command は versioned JSON を出力します。
自動処理では human-readable message の文字列一致ではなく、status、diagnostic category、schema version、exit code を使います。
serve --json は長時間動作するため、一つの JSON document ではなく JSON Lines を stdout へ出します。
起動完了時に ready、SIGINT/SIGTERM による正常終了時に stopped を出します。
experiment run は --json の有無にかかわらず stdout へ JSON result を出します。
fibril_sim で利用できる command は validate、inspect、run、serve、runtime、benchmark、trace、experiment、render、record、view、replay、calibrate です。
fibril_sim model は MJCF から派生 artifact を生成する model tooling をまとめ、現在は export-urdf を提供します。
validate
Manifest から SimulationPlan を構築し、model compile、binding、schedule、global invariant を検証します。
例:
--json を付けると CLI envelope と Plan schema version を JSON で返します。
inspect
解決済み SimulationPlan を表示します。
human output と JSON output は、Component、extension、binding、schedule、provenance など同じ resolved contract を異なる表現で示します。
run
Plan から Instance を作り、固定数の physics step を実行します。
| Option | Default | Meaning |
|---|---|---|
--steps |
1 |
実行する physics step 数 |
--trace |
none | semantic MCAP trace の出力先 |
--trace-detail |
causal |
trace capture policy |
--trace-state-every |
policy default | numerical / full の numerical state decimation |
--json |
false | machine-readable output |
--steps 0 は無効です。
--trace-state-every は numerical または full と組み合わせます。
serve
runtime.mode: realtime_paced の Plan を ROS なしで live 実行し、SimulationRuntime の typed Fibril Simulation IPC endpoint を公開します。
serve は SimulationHost の realtime pacing を使います。
fixed-step の offline execution は run を使い、serve へ external step command を追加しません。
endpoint の default は default です。通常の一つの simulator だけを起動する構成では endpoint を指定しません。
同じ host で複数 simulator を同時に動かす場合だけ --endpoint ID を指定し、view、record、compatible simulated driver に同じ ID を渡します。
同じ endpoint ID を二つの server が同時に所有することはできません。
runtime
running Fibril Simulation IPC endpoint に対する最小 control surface です。
status は endpoint が接続可能なら終了 code 0、見つからなければ 1 を返します。
reset は SimulationConnection の control boundary 経由で episode reset を要求します。
arbitrary ExternalInput の注入はこの command の責務に含めません。
benchmark
ROS、viewer、wall-clock pacing を含めず、同じ SimulationInstance::step() lifecycle の headless throughput を測ります。
default は warmup 1000 step、measured 10000 step です。
出力には simulated / wall seconds、RTF、per-step wall duration の p50 / p95 / p99、completed boundary の contact / constraint count、最大 solver iteration の mean / max が含まれます。
--lazy-completed-boundary-forward は、completed boundary の position / velocity derived state を常に確定した上で、acceleration / constraint suffix だけを Device、Interaction、Observer、trace、snapshot が要求するまで遅延します。
これは physics parameter ではなく execution policy です。
未知の custom runtime は FullForward を要求する保守的 contract のため、明示的に read set を宣言しない限り suffix は省略されません。
通常の SimulationHost はこの lazy policy と一つの private-state query worker を既定で使いますが、benchmark は比較実験のため明示optionで切り替えます。
--profile は canonical phase、Device、physics/MuJoCo subphase の wall-time counter を追加します。
--no-debug-events は benchmark 中の human-readable RuntimeDebugEvent 構築を無効化し、diagnostic formatting cost を分離します。
この command は ROS executor、DDS、viewer、RViz の performance benchmark ではありません。
headless benchmark が十分速く ROS / viewer 付き実行だけ遅い場合は、simulation physics parameter を先に変更せず integration 側を別に profile します。
trace
persist した Fibril semantic / physical trace を、run 全体の再実行なしに調べます。
Trace の情報表示
frame 数、episode / session time、trace schema、観測された actuator endpoint、contact object、semantic event、Device を要約します。 保存されている場合は model / compiled-model / Manifest / parameter-set hash、asset hash、MuJoCo version、extension、episode seed を provenance として表示します。
Trace の query
--manifest は --signal の joint、sensor、body、actuator endpoint の semantic name を current compiled model へ解決する場合だけ必要です。
input / Device / semantic event / Domain / contact だけを問い合わせる場合は trace 自体に identity が記録されているため Manifest は不要です。
現在の named signal selector は次です。
actuator:<endpoint> は MuJoCo actuator name ではなく、Fibril の actuator endpoint ID を指定します。
--contact は contact の geom / flex name に対する substring filter です。
--active-contacts-only を指定すると、solver constraint として instantiate された contact だけを返します。
--input は committed ExternalInput source ID、--device は acquisition / delivery の Device ID、--event は semantic event name、--domain は Domain ID を substring で絞ります。
Trace の比較
二つの persisted trace を同じ D1/D2 comparison contract で比較します。
--scope の default は state、--tolerance の default は 0.0 です。
どちらかの trace に SimulationTraceFrame がない場合は比較を成立させず data error とします。
divergence が見つかった場合は終了 code 3 を返します。
一つの failing run の causal timeline を調べる場合は trace query、recorded ExternalInput を再実行する場合は replay、既に存在する二つの trace を比較する場合は trace compare を使います。
render
optional fibril_sim_render package の headless EGL renderer を使い、interactive viewer を操作せず複数視点の inspection PNG を出力します。
visual は primary authored geometry の group 0 と --visual-group で指定した render-only group を表示します。
collision は render-only group を除いた geometry、overlay は全 group を表示します。
render-only geometry の既定 group は 3 です。
別 convention の model では --visual-group で明示的に変更します。
--focus-body を指定すると、その body subtree の current geom bounds から look-at と camera distance を計算します。
--trace を指定した場合は recorded committed ExternalInput を fresh Instance に replay し、指定 boundary tick の state を render します。--boundary-tick を省略すると最終 recorded tick を使います。
headless inspection は model geometry / collision / frame / contact を同じ pose で比較する用途です。interactive simulation 操作は view を使います。
view
optional fibril_sim_viewer package の interactive Debug Viewer を起動します。
viewer は Manifest や render model を構築しません。
serve や ROS frontend が公開する SimulationConnection から、runtime が確定した presentation model と SimulationPlan metadata を一度取得し、その後は authoritative render state を購読します。
表示 model の選択や physics state の所有は runtime 側に残るため、viewer 起動時に --render-model を指定する必要はありません。
--endpoint の default は default で、複数 simulator を同時に起動するときだけ指定します。
record
optional fibril_sim_video package の EGL offscreen renderer を使い、running Fibril Simulation instance の IPC render state を MP4 に記録します。interactive viewer や X11/Wayland の window capture は使いません。
recorder は endpoint が現れるまで待つため、simulation より先に起動できます。--endpoint を省略すると default へ接続します。一度接続した後は endpoint が消えると MP4 を finalize して終了します。test の先頭を取り逃がさないため、system test の起動前に recorder を起動してください。
record の既定 geometry mode は visual です。group 0 の物理兼表示 geometry と既定の render-only group 3 を描画し、collision/debug proxy group は表示しません。確認用途で必要な場合だけ --mode collision または --mode overlay を明示します。
--view top と --view iso は model 内の最大の有限 plane を arena floor として自動 framing します。frame pacing は IPC render state の EpisodeTime に従い、episode reset が入った場合は reset 前の partial video を破棄して最終 MP4 に pre-roll を残しません。
replay
recorded semantic trace の ExternalInput を commit tick とともに新しい Instance へ replay し、生成された trace と比較します。
--scope の default は state、--tolerance の default は 0.0 です。
trace に SimulationTraceFrame が一件もない場合は replay data error になります。
replay Instance の episode seed は Manifest default ではなく trace の最初の frame に記録された seed を使います。
divergence が見つかった場合は終了 code 3 を返します。
experiment
experiment は、canonical SimulationManifest と parameter overlay を使って baseline と parameter variant を同じ model topology で比較します。
scalar tuning のために MJCF を複製せず、variant ごとの差分は parameter_values だけで表します。
experiment の parameters.baseline_overlay が canonical Manifest の parameter_overlays に同じ parameter_set_id と同じ content hash で含まれている場合、その persistent overlay は run ごとの in-memory baseline/variant overlay に置き換わります。
このため production と同じ Manifest を experiment から直接参照でき、model、component graph、scenario、無関係な overlay を複製する必要はありません。
同じ parameter_set_id なのに content hash が異なる場合は provenance drift として拒否します。
run は各 variant の parameter diff、metric、assertion、model hash、compiled model hash、trace path を JSON に記録します。
parameter の採用判断は experiment 単独では行わず、実データ、holdout、task-level validation と分けて扱います。
calibrate
versioned calibration request を読み、Ceres optimizer で Manifest-bound parameter を fitting します。
request の内容は Calibration を参照してください。
--output は versioned full result、--output-overlay は Manifest の parameter_overlays から利用できる fitted parameter artifact だけを保存します。
model export-urdf
MJCF を source of truth とした kinematic description を URDF に投影します。
入力は raw MJCF 一つ、または --manifest で指定する SimulationManifest 一つです。
Manifest を使う場合は positional model の代わりに次の形式を使います。
Manifest path を指定した場合も URDF を authored simulation input として扱うわけではありません。
MJCF を読み出して projection し、simulation parameter overlay は適用しないため、overlay が存在する場合は warning を出します。
--root は export する robot subtree の root body、--name は生成する URDF robot name を指定します。
--fallback-effort と --fallback-velocity は MJCF から直接導出できない URDF joint limit の fallback です。
Exit code と error output
argument parsing error は 64、Plan construction の BuildError は 2、runtime または data error は通常 1 を返します。
replay または trace compare で比較結果が divergence の場合は 3 を返します。
--json を指定した error は versioned diagnostic object として標準出力へ出します。
human-readable mode では diagnostic message を標準エラーへ出します。
automation では message text の文字列一致ではなく、JSON の category、code、schema version を使って判定してください。