基本概念

Fibril Simulation の設定は、物理モデル、simulation composition、解決済み計画、一回の実行状態という四つの層に分かれます。この区別を保つと、同じ robot model を複数の test や calibration run へ再利用しやすくなります。

MuJoCo model の役割

MuJoCo model は MJCF で記述する物理世界です。 body、joint、geom、actuator、sensor、camera、site などの MuJoCo object を定義します。

Fibril の virtual sensor や actuator は、Manifest に書かれた object name を使ってこの model に binding されます。したがって、Component の設定で参照する名前は MuJoCo model の compile 後にも一意に解決できる必要があります。

SimulationManifest の役割

物理世界をどのような simulation として使うかは SimulationManifest に記述します。 Manifest は model path、Component、extension、trace、runtime option を一つの versioned contract として保持します。 physics timestep は Manifest ではなく MJCF の <option timestep="..."> が source of truth です。

Manifest は「起動スクリプト」ではありません。読み込み後に model と合わせて検証され、実行前に解決できる不整合は Plan construction の段階で失敗します。

Component の役割

Component は、MuJoCo model 上に Fibril の simulation semantics を追加する再利用単位です。標準 Component には actuator、joint encoder、IMU、rangefinder、planar LiDAR、camera などがあります。

たとえば fibril_sim/encoder は MuJoCo の hinge joint を参照し、counts per revolution、offset、noise、acquisition period、latency を適用した Device output を生成します。 MuJoCo の joint 自体を別の物理 joint に置き換えるわけではありません。

SimulationPlan の役割

Manifest と model を解決すると SimulationPlan が生成されます。 Plan は compile 済み MuJoCo model、Component descriptor、binding、schedule、runtime option、provenance などを保持する immutable な実行 blueprint です。

Plan の内容は fibril_sim inspect で確認できます。同じ Plan から複数の SimulationInstance を生成しても、各 run の mutable state は共有されません。

SimulationInstance の役割

SimulationInstance は一回の simulation run に属する mutable state です。 MuJoCo state、EpisodeTime、SessionTime、Device queue、ActuatorDriver state、ExternalInput、domain state、RNG、trace state は Instance ごとに分離されます。

step() は physics timestep 一つ分だけ Instance を進めます。 reset() は同じ Plan を使ったまま episode-local state を初期化します。

SimulationRuntime と SimulationConnection

live simulation の process boundary は SimulationRuntime が所有します。 SimulationRuntime は構築済み SimulationPlan から SimulationHost と SimulationServer をまとめて保持し、ROS 2 や GUI に runtime ownership を持ち込みません。

SimulationHost は一つの owner thread で SimulationInstance を進めます。外部 client は SimulationConnection を使って typed ExternalInput、DeviceOutput、completed-frame timing、render observation、control にアクセスし、active MuJoCo state を直接参照しません。

production controller と SIL controller は SimulationInstance の外側に置きます。 controller output はほかの非同期入力と同じ ExternalInput contract を通って runtime に入ります。

Device と actuator endpoint

sensor 系 Component は Device として acquisition と delivery を持ちます。取得した瞬間の値と controller から見える時刻を分けるため、period と latency を個別に設定できます。

actuator 系 Component は actuator endpoint を提供します。 controller が出した command、transport release、driver semantics を適用した値、MuJoCo actuator への application を分離して扱います。

ExternalInput の役割

ROS callback や recorded input のように simulation 外から到着する値は ExternalInput として Instance へ enqueue します。 enqueue は active MuJoCo state を直接変更せず、runtime の commit boundary で可視化されます。

この設計により、callback thread の到着タイミングが physics state の途中へ割り込むことを避けられます。 ROS integration ではこの ingress-only contract をそのまま利用します。

Trace と provenance

trace を有効にすると、Device、ExternalInput、controller command、actuator application、post-physics state などの semantic record を保存できます。永続化形式には MCAP を使用します。

Plan は model、Manifest、parameter set、resolved asset、MuJoCo version、extension、episode seed などの provenance も保持します。異なる run を比較するときは、数値結果だけでなく「何を使って実行したか」も確認できます。