アーキテクチャ

Fibril Simulation は、physics engine、deterministic runtime、virtual hardware、integration を一つの package に集約しません。 active-state ownership と依存方向を package boundary で固定することで、headless test と ROS integration が同じ runtime contract を共有できるようにしています。

主要 abstraction

SimulationManifest
       |
       v
SimulationBuilder ---- SimulationExtension
       |                    |
       |                    +--> Component types / domain semantics
       v
SimulationPlan
       +--> create_instance() --> SimulationInstance
       |                           |
       |                           +--> MuJoCo mjData
       |                           +--> Device runtimes
       |                           +--> ActuatorDriver runtimes
       |                           +--> ExternalInput mailbox
       |                           +--> domain state
       |                           +--> trace state
       |
       +--> SimulationRuntime
              |
              +--> SimulationHost --> SimulationInstance
              |
              +--> SimulationServer <----> SimulationConnection

SimulationBuilder は mutable construction object です。 Component contribution と extension contribution を同じ capability registry に集約し、MuJoCo binding と global invariant を一度だけ解決した後に immutable SimulationPlan を生成します。

SimulationPlan は run 間で共有できる resolved blueprint です。現在の Plan inspection schema は 2.2 で、model source、scenario reference、Component、resolved actuator assembly、resolved extension identity、capability-local binding、kernel schedule、Device-local acquisition schedule、authority、provenance などを公開します。

SimulationInstance は一つの run に属する mutable state を所有します。 Plan を共有しても mjData、queue、RNG、ActuatorDriver state、domain state、clock、trace は Instance 間で共有されません。

Runtime と integration の分離

fibril_sim_core、fibril_sim_mujoco、fibril_sim_runtime は reusable runtime 層です。 fibril_sim_models はその runtime contract を利用する reusable-model 層で、standard Component、physical model、MuJoCo model plugin、共有 profile / preset を提供します。これらの package は ROS 2、ament index、pluginlib を直接必要としません。その理由は「ROS を使わない方が軽いから」だけではありません。 reusable runtime が integration framework の callback model や resource lookup に依存すると、headless test と production integration で実行 contract が分岐するためです。

依存方向は fibril_sim_models -> fibril_sim_mujoco -> fibril_sim_core を基本とし、fibril_sim_mujoco から standard model package へ逆依存させません。 runtime は model の種類を知らず、model 側が binding、read view、Interaction、body-wrench contribution などの runtime primitive を組み合わせます。

fibril_sim_runtime の SimulationRuntime は、一つの run に対する SimulationHost と SimulationServer の lifetime を ROS 2 から独立して所有します。 SimulationHost は mutable SimulationInstance の owner thread を持ちます。 SimulationServer と SimulationConnection は、typed ExternalInput、DeviceOutput、completed-frame timing、render observation、control を same-host IPC で公開する実行境界です。 transport は iceoryx2 で実装しますが、client-facing API から transport primitive は隠します。 compatible simulated driver、viewer、recorder は同じ connection boundary を使うため、ROS callback や GUI thread から mutable simulation state を直接操作しません。 ROS 2 は Host 内部 transport ではなく、production API と simulation observation の integration graph としてその外側に置きます。

ament resource resolution、pluginlib loading、standard ament-backed SimulationPlan composition は fibril_sim_ament が担当します。 ROS message、/clock、rosbag2 は fibril_sim_ros が担当します。このため標準 ROS frontend は構築済み Plan から SimulationRuntime を生成する薄い adapter に留まります。

Component と Extension

Component は一つの Manifest declaration から Device、actuator endpoint、ActuatorDriver、prescribed state などの runtime capability を生成する再利用単位です。 standard Component は fibril_sim_models に置きます。

fibril_sim_models は Component だけを意味しません。 finite compliant attachment や tire force/slip law のような reduced-order physical model、fibril_sim.position_pid / fibril_sim.tire_contact のような MuJoCo model plugin、model と同じ ownership を持つ generic profile / MJCF preset も同じ reusable-model layer に置きます。そのため fibril_sim_mujoco は concrete model plugin 名や command semantics を解釈しません。 plugin-backed actuator は runtime では PluginDefined として inspection され、fibril_sim_models の actuator-semantics adapter が既知の reusable plugin contract を Position / Velocity / Effort semantics へ解決します。同様に construction-time calibration は plugin_attribute という generic named-plugin-instance target を使い、runtime に position_pid 固有 parameter kind を追加しません。 robot 固有 geometry、mounting、installed-unit calibration、competition threshold は application 側に残します。

SimulationExtension は application 固有の capability を追加する boundary です。 extension は Declare と Configure の二段階 lifecycle を持ち、Component type や domain semantics を core package の enum に追加せず composition できます。

competition rule や game semantics を standard Component に取り込むと、reusable virtual hardware と application policy の依存方向が逆転します。そのため domain-specific behavior は extension 側に置きます。

Deterministic runtime の実行順序

一回の SimulationInstance::step() は固定された 13 phase を同じ順序で実行します。 execution mode は wall-clock pacing を変えられますが、この simulation-visible ordering は変えません。

外部 thread からの input は mailbox に enqueue され、ExternalInputCommit でだけ可視になります。 controller output も同じ ExternalInput boundary を通るため、SIL 用の in-process controller だけが別の runtime ordering を持つ構造を作りません。

Reproducibility の範囲

Fibril Simulation は input ordering、schedule、named RNG、Plan provenance、semantic trace を固定して deterministic replay を構成します。一方、異なる platform 間の全 floating-point bit pattern が常に一致するという D3 bitwise reproducibility は contract に含めません。

数値比較は scope と tolerance を明示し、semantic equivalence と numerical closeness を分けて診断します。