SimulationManifest リファレンス

SimulationManifest は、MuJoCo model と Fibril Simulation の構成を結び付ける versioned YAML contract です。現在の schema は 3.3 です。

未知の top-level field と未知の nested field は読み込み時に拒否されます。同じ major version でも実装より新しい minor version は受理されません。

全体構造

schema_version:
  major: 3
  minor: 3

model:
  path: model.xml

parameter_overlays:
  - calibration/robot_physical.yaml

extensions:
  - class: package/ExtensionClass
    config: {}

assemblies:
  - id: drive0_axis
    component: drive0
    transmission:
      type: wheel
      radius_m: 0.046

components:
  - id: front_lrf
    type: fibril_sim/rangefinder
    config:
      sensor: front_rangefinder_sensor
      period_s: 0.01
      range_min: 0.05
      range_max: 10.0

trace:
  enabled: true

scenario: scenario.yaml

runtime:
  mode: deterministic_ci
  episode_seed: 42

schema_version と model は必須です。それ以外の top-level section は省略できます。

Construction composition の構成

ROS 2 の ament integration から Manifest を読み込む場合は、strict な SimulationManifest へ変換する前に construction composition を使えます。これは複数 robot や用途別 product を構成するための前処理であり、SimulationPlan の runtime semantics は変更しません。

construction source では、strict Manifest の field に加えて imports、composition_profiles、sets、各 collection entry の groups を記述できます。 fibril_sim_ament がそれらを解決してから construction metadata を除去し、結果を通常の strict parser へ渡します。したがって、construction metadata を含む source を load_manifest_file() へ直接渡すことはできません。 ament 環境では load_ament_manifest_file() を使います。

Product profile の指定

一つの source から core、full、diagnostic などの product を選ぶ場合は composition_profiles と groups を使います。

schema_version:
  major: 3
  minor: 3

composition_profiles:
  core:
    exclude_groups: [diagnostic]
  full: {}

components:
  - id: drive0
    type: fibril_sim/motor
    config: {}

  - id: debug_pose
    type: fibril_sim/body_kinematics
    groups: [diagnostic]
    config: {}

profile は construction entry を選別します。 groups を持たない entry は常に残り、include_groups を指定した場合は一致する group を持つ entry を追加し、exclude_groups に一致する entry は除外します。 Component が除外された場合、その Component を参照する assemblies も最終 document から除外されます。

これは Component type 固有の Component profile とは別の機構です。 construction profile は「その simulation product に何を含めるか」を選び、Component profile は「選ばれた Component instance をどの device/transport parameter で構成するか」を決めます。

同型 entry の `sets`

同じ構造の Component、assembly、ROS bridge を複数 instance に展開する場合は sets を使います。 template を各 instances mapping に再帰的に合成し、通常の collection entry へ展開してから import transform と product profile filtering を適用します。文字列置換や index macro は行わないため、stable ID や MuJoCo object 名の違いは各 instance に明示します。

sets:
  components:
    - template:
        type: fibril_sim/motor
        config:
          profiles:
            device: robomaster_m3508_p19
            transport: robot_drive_path
          timeout_s: 0.2
      instances:
        - id: drive0
          config: { actuator: motor0_wheel_joint }
        - id: drive1
          config: { actuator: motor1_wheel_joint }

  assemblies:
    - template:
        transmission:
          type: wheel
          radius_m: 0.046
      instances:
        - { id: drive0_axis, component: drive0 }
        - { id: drive1_axis, component: drive1 }

SimulationManifest construction source では sets.components と sets.assemblies、ROS frontend construction source では sets.bridges を使えます。 template に id は置かず、各 instance が non-empty の id を所有します。 instance mapping は template を deep-merge するため、共通の nested config を保ったまま actuator、sensor、topic など必要な leaf だけ差し替えられます。 groups も template または instance に置けるため、展開後は通常の entry と同じ profile filtering を受けます。

Manifest import の指定

imports は別の construction source から extensions、assemblies、components を取り込みます。 import source は同じ directory からの相対 path または package:// URI で指定できます。

imports:
  - source: r2.yaml
    component_prefix: r2_
    component_reference_keys: [command_source]
    mujoco:
      prefix: r2_
      scalar_keys: [body, joint, actuator, sensor]
      list_keys: [joints, geoms]
      remap:
        local_book: shared_book

component_prefix は imported Component ID と assembly の Component reference に適用されます。 Component config 内で別 Component を参照する field は component_reference_keys または component_reference_list_keys に明示します。

MuJoCo object reference は mujoco.scalar_keys と mujoco.list_keys に明示した field だけを書き換えます。 list_keys は一次元配列だけでなく、contact group のような入れ子の配列に含まれる文字列も書き換えます。通常は mujoco.prefix を付け、共有 world object のように prefix しない対象だけを mujoco.remap へ記述します。すべての YAML string を推測で書き換える仕組みではありません。

import source の parameter_overlays も同時に取り込まれます。 MuJoCo target には同じ mujoco.prefix / mujoco.remap、Component config target には同じ component_prefix が ordered transform として付与されます。したがって standalone robot の calibration artifact を複製して r2_ などを手書きする必要はありません。同じ module を複数 namespace へ import する場合も、一つの overlay artifact を各 instance の transform 付きで再利用できます。

imported Component または extension に product 固有の差分が必要な場合は component_overrides と extension_config_overrides を使えます。 override は mapping を再帰的に合成し、source robot の canonical definition 自体は変更しません。

inherit: true を指定した import は、import先で未指定の root field も引き継ぎます。これは focused fixture が canonical product を再利用し、model や scenario だけを差し替える場合に使います。循環 import は construction error です。

composition 後の YAML content hash は Manifest provenance の source hash として保持されます。そのため同じ source pathでも profile、imported content、override の解決結果が変われば別の construction identity になります。

fibril_simulation_node は manifest_profile parameter で Manifest profileを選び、ros_profile parameterでROS frontend側のprofileを選びます。 CLIでは validate、inspect、run、benchmark が --manifest-profile <name> を受け付けます。

fibril_sim validate robot.yaml --manifest-profile core
fibril_sim inspect robot.yaml --manifest-profile full --json
fibril_sim benchmark robot.yaml --manifest-profile core --steps 10000

`schema_version`

Field	Type	Required	Meaning
`major`	uint32	yes	Manifest contract の major version
`minor`	uint32	yes	Manifest contract の minor version

major version が一致しない Manifest は Plan construction で拒否されます。現在の contract を新規に書く場合は major: 3、minor: 3 を指定します。同じ major version の minor <= 3 を読み込めます。

`model`

`model.path`

MuJoCo root model の path を指定する必須 field です。通常の file path と package:// URI を受け付けます。

相対 file path は Manifest ファイルの directory を基準に absolute path へ解決されます。 package:// URI は logical URI のまま MuJoCo resource provider へ渡されます。

model composition と physics timestep は Manifest では再定義しません。 submodel composition は MuJoCo の <asset><model> と <attach>、physics timestep は MJCF の <option timestep="..."> を使います。 compile 後の mjModel.opt.timestep が Fibril の schedule validation に使われる唯一の physics grid です。

`parameter_overlays`

parameter_overlays は、versioned calibration artifact を Plan construction input として適用する resource reference の sequence です。相対 path は Manifest directory を基準に解決し、package:// URI は logical reference のまま ResourceProvider へ渡します。

schema_version:
  major: 3
  minor: 1
model:
  path: robot.xml
parameter_overlays:
  - calibration/robot_physical.yaml

schema 3.3 では、construction import がnamespaceを保持するためにexpanded referenceも使えます。通常これは fibril_sim_ament が imports から自動生成するため、robot source側で直接記述する必要はありません。

parameter_overlays:
  - source: calibration/robot_physical.yaml
    transforms:
      - mujoco:
          prefix: r2_
          remap:
            local_book: shared_book
        component_prefix: r2_

transforms は内側のimportから外側のimportへ記録順に適用します。 MuJoCo target は各段で remap を先に確認し、一致しない名前だけに prefix を付けます。 Component config target には component_prefix を付けます。 overlay本体のparameter ID/value/content hashは変更しません。

artifact は calibration result の parameter_overlay と同じ schema 1.1 を使います。

schema_version:
  major: 1
  minor: 2
parameter_set_id: robot-physical-2026-08-17
parameter_values:
  drive_resistance_ohm: 0.6
  staff_pitch_kp: 11.1
targets:
  drive_resistance_ohm:
    - mujoco:dcmotor_resistance:drive0:0
  staff_pitch_kp:
    - mujoco:plugin_attribute:staff_pitch_pid:kp

component_config target は Component profile composition の後、ComponentFactory の validation より前に適用されます。 mujoco target は MJCF parse 後、mj_compile より前に typed model field へ適用されます。 mujoco:plugin_attribute:<instance>:<attribute> は named MuJoCo plugin instance の attribute を generic に更新します。 plugin の種類や attribute の意味は reusable model 側が所有し、runtime overlay は concrete plugin 名を知りません。同じ effective target へ異なる parameter が書き込もうとした場合は construction error になります。

persistent overlay は nominal MJCF の文字列を書き換える仕組みではありません。 nominal model、robot-specific transmission/controller、実機同定した effective correction を別 resource として保持するための construction layer です。

overlay artifact の content hash は resolved asset provenance に保存されます。 target identity と effective value は parameter_set_hash に入るため、同じ Manifest と nominal MJCF を使っていても calibration artifact の値が変われば parameter identity も変わります。

`extensions`

SimulationExtension plugin を読み込む sequence です。

Field	Type	Required	Meaning
`class`	string	yes	pluginlib class name
`config`	mapping	no	extension 固有 configuration

同じ plugin class を一つの Manifest で複数回指定することはできません。 config を省略した場合は空 mapping として扱われます。

extensions:
  - class: fibril_sim_render/RenderedSensorExtension

extension は Component type と runtime capability を Plan construction 中に追加できます。 Extension 間の dependency は plugin implementation の dependencies() が extension ID で宣言します。 dependency は自動 load されないため、依存先の extension も Manifest または Builder API から明示的に追加する必要があります。 Declare と Configure の順序は dependency graph と stable extension ID から決まり、extensions sequence の記載順は semantic ordering には使われません。 resolved extension の ID、version、dependencies、config hash は Plan inspection と provenance に保持されます。

`assemblies`

assemblies は、actuator device と robot-specific transmission の組み合わせを一度だけ宣言する construction contract です。 MJCF と Component config の両方へ同じ transmission 由来の数値を手入力するための section ではありません。

例えば wheel drive は、wheel radius を assembly に記述します。

assemblies:
  - id: drive0_axis
    component: drive0
    transmission:
      type: wheel
      radius_m: 0.046

components:
  - id: drive0
    type: fibril_sim/motor
    config:
      profiles:
        device: robomaster_m3508_p19
        transport: robot_drive_path
      actuator: drive0_actuator

この宣言から construction 時に、MuJoCo actuator の transmission gear と fibril_sim/motor の logical_units_per_joint_unit を同じ入力から導出します。 raw MJCF の actuator gear と Component config の logical_units_per_joint_unit に同じ情報を重複記述すると construction error になります。

assemblies は YAML に書かれますが、すべてが virtual-device configuration という意味ではありません。 transmission の ratio や pulley radius は robot の物理 construction metadata であり、resolved gear は mj_compile より前に mjSpec へ materialize されます。 Component 側には、同じ assembly から controller-facing logical coordinate と current reporting semantics だけを materialize します。

Assembly field の意味

Field	Type	Required	Meaning
`id`	string	yes	assembly の stable ID
`component`	string	yes	assembly が構成する `fibril_sim/motor` または `fibril_sim/motion_motor` instance ID
`transmission`	mapping	yes	physical transmission declaration
`actuator_count`	uint32	no	同じ mechanical axis を駆動する同種 actuator 数。省略時は `1`
`logical_direction`	`-1` or `1`	no	production logical coordinate の符号。省略時は `1`
`logical_scale`	positive number	no	physical joint coordinate から production logical coordinate への追加 scale。省略時は `1`

一つの Component を複数 assembly から所有することはできません。 assembly が参照する Component が存在しない場合も construction error になります。

`transmission`

初期 contract では次の4種類を扱います。

`type`	Required fields	Resolved actuator gear	Typical use
`direct_rotary`	none	`direction`	direct-drive rotary axis
`gear_rotary`	`ratio`	`direction * ratio`	external gearbox or belt reduction
`wheel`	`radius_m`	`direction * ratio`	rotary wheel with controller-facing linear coordinate
`pulley_linear`	`radius_m`	`direction * ratio / radius_m`	rotary actuator driving a slide through pulley or pinion

ratio は省略時 1、direction は省略時 1 です。 radius_m は wheel と pulley_linear で必須です。 direct_rotary では ratio を 1 以外にできません。

wheel では、既定の logical coordinate scale は radius_m です。したがって joint angular velocity rad/s から controller-facing wheel speed m/s を導出できます。 pulley_linear の MuJoCo joint はすでに slide coordinate を持つため、既定の logical scale は 1 です。 production encoder coordinate が slide coordinate と異なる場合だけ logical_direction と logical_scale を assembly に明示します。

Parallel actuator の表現

同じ axis を複数 actuator で駆動する場合は actuator_count を使います。

assemblies:
  - id: elevator_axis
    component: elevator
    actuator_count: 2
    logical_direction: -1
    logical_scale: 1.9142857142857144
    transmission:
      type: pulley_linear
      radius_m: 0.02101

現在の fibril_sim/motor contract では、device profile の feedback_current_per_force を actuator_count で割り、aggregate axis force から1 actuator あたりの reported current を導出します。 instance config に parallel-motor 用の別 feedback_current_per_force を重複記述することはできません。

Construction order の決定

assembly と calibration の適用順は固定されています。

Component profile composition
        |
Assembly-derived Component values
        |
Component parameter overlay
        |
ComponentFactory

MJCF parse
        |
Assembly-derived actuator transmission
        |
MuJoCo parameter overlay
        |
mj_compile

この順序により、nominal assembly を実機完成前に使い、実機完成後は同じ semantic target へ calibration overlay を追加できます。 resolved assembly は Plan inspection に残り、assembly の入力と derived gear は parameter_set_hash に参加します。

`components`

Component instance の sequence です。

Field	Type	Required	Meaning
`id`	string	yes	Plan 内で Component を識別する stable ID
`type`	string	yes	registered Component type ID
`config`	mapping	yes	Component type 固有 configuration

components:
  - id: front_lrf
    type: fibril_sim/rangefinder
    config:
      sensor: front_rangefinder_sensor
      period_s: 0.01
      range_min: 0.05
      range_max: 10.0

標準 type の一覧と config schema は Component reference を参照してください。 Component が生成する Device schedule、actuator endpoint、prescribed state authority などは ComponentDefinition から導出されるため、Manifest から別々に重複定義しません。

Component profile の指定

Component type は再利用可能な virtual-device configuration を profile として登録できます。 profile は ComponentFactory が解釈する前に ComponentRegistry が effective config へ解決します。

一つの Component は device、transport、empirical などの facet ごとに profile を一つずつ選択できます。 profile 同士は order-dependent な last-wins merge を行わず、異なる profile が同じ leaf field に異なる値を与える場合は construction error にします。意図した override は Component instance の config に明示します。

components:
  - id: steering0
    type: fibril_sim/motor
    config:
      profiles:
        device: robomaster_m2006_p36
        transport: robot_can_fast_path
      actuator: steering0_actuator

profile ID は Component type ごとの namespace に属します。例えば fibril_sim/motor と fibril_sim/ahrs は同じ文字列の profile ID を独立に登録できます。

profile defaults の mapping は再帰的に合成します。 profile 同士で scalar または sequence が競合する場合は拒否し、instance config だけが合成済み値を置換できます。解決後は top-level の profiles を除去して ComponentFactory へ渡すため、Component implementation は profile 選択ではなく effective config のみを検証します。

未登録 profile、空の profile ID、Component type に profile catalog が存在しない参照は Plan construction 中に拒否されます。 SimulationExtension も declare() 中に Component factory とその profile を登録できます。

SimulationPlan は選択した facet/profile ID と effective config の hash を保持します。したがって profile ID を変えず catalog 内の値だけを変更した場合も parameter_set_hash が変化します。

Profile catalog schema の形式

複数の Component type にまたがる profile は、versioned YAML catalog として登録できます。 catalog の schema は Component type 固有ではありません。

schema_version:
  major: 1
  minor: 2

profiles:
  - type: fibril_sim/motor
    id: robomaster_m2006_p36
    facet: device
    config:
      feedback_current_per_force: 5.555555555555556

  - type: fibril_sim/ahrs
    id: r6093u_nominal
    facet: device
    config:
      period_s: 0.01
      yaw_reference: initial

各 entry は type または types のどちらか一方と、id、facet、config を必須 field とします。 config は mapping で、Component instance の選択に使う top-level profiles field を含めることはできません。 catalog は Component factory の登録後、registry が freeze される前に読み込みます。未知の field、未対応 schema version、未知の Component type、重複 profile ID は registration error になります。

同じ transport/device contract を複数の互換 Component type が共有する場合、schema 1.2 では type の代わりに types を指定できます。これは同じ profile definition を各 Component type namespace へ登録するだけで、type 間に継承関係を作るものではありません。

profiles:
  - types: [fibril_sim/motor, fibril_sim/kinematic_motor]
    id: robot_can_40hz_path
    facet: transport
    config:
      application_period_s: 0.002
      feedback_period_s: 0.025

標準 Component の built-in profile は fibril_sim_models/profiles/component_profiles.yaml にこの schema で保存されます。 register_standard_components() は factory だけを登録します。標準 profile catalog は register_standard_component_profiles() へ resource path を明示して登録します。この分離により fibril_sim_models 自体は ament package lookup に依存せず、package:// の解決は integration layer が登録した MuJoCo ResourceProvider に委譲できます。

`trace`

`trace.enabled`

semantic trace の生成を有効にする boolean です。

trace:
  enabled: true

CLI の run --trace もその run について trace policy を有効化します。

`scenario`

simulation が参照する generic initial-condition resource を scalar string で指定します。空文字列は受理されません。

通常の file path と package:// URI を使えます。相対 file path は Manifest directory を基準に absolute path へ解決され、resolved reference は SimulationPlan に保持されます。

scenario: scenarios/controller_sil.yaml

Scenario resource 自体も Fibril core の versioned contract です。現在の schema は 2.1 です。

schema_version:
  major: 2
  minor: 1

keyframe: initial_pose

initial_joint_states:
  - joint: steering_joint
    qpos: [0.0]
    qvel: [0.0]

initial_external_inputs:
  - source: drive_command
    payload:
      velocity: 0.0
      enabled: true

keyframe は optional な MuJoCo keyframe name です。 Plan construction で compile 済み model に存在することを検証します。

initial_joint_states は joint ごとの complete atomic qpos / qvel を指定します。 joint name と joint type から必要な vector 幅を Plan construction で解決し、未知の joint、不完全な state、同じ joint の重複、continuous prescribed authority と競合する joint state を拒否します。

initial_external_inputs は ExternalInput source と初期 payload を指定します。 source は extension と Component の構成後に解決され、未知の source、replay codec を持たない source、codec で decode できない payload、同じ source の重複を拒否します。

Instance の作成時と episode reset 時には、まず external input の初期値を committed value として復元し、MuJoCo keyframe、initial_joint_states、continuous prescribed state の順で物理 state を構成してから derived state を再計算します。この resource は competition rule や任意の application state を格納する拡張用 YAML ではありません。 application 固有の scenario semantics が必要な場合は SimulationExtension 側の config/resource として分離します。

`runtime`

`runtime.mode`

host execution policy を指定します。省略時は unbounded です。

Value	Intended use
`unbounded`	wall-clock pacing を要求しない実行
`realtime_paced`	real-time paced host
`deterministic_ci`	CI と deterministic test
`rendered`	rendering を伴う host
`operator_training`	operator training host

mode は host policy であり、SimulationInstance の canonical runtime phase ordering を変更しません。

`runtime.episode_seed`

run-local named RNG stream の基準 seed を uint64 で指定します。省略時は 0 です。

runtime:
  mode: deterministic_ci
  episode_seed: 12345

Path resolution の規則

Manifest 自身の file path と通常の model.path、scenario path は absolute path へ正規化されます。 package:// resource は logical identity を保ったまま MuJoCo ResourceProvider へ渡されます。

この差は provenance にも反映されます。 logical URI を install-space の偶然の absolute path に置き換えず、同じ resource identity として追跡できます。

SimulationManifest リファレンス

全体構造

Construction composition の構成

Product profile の指定

同型 entry の sets

Manifest import の指定

schema_version

model

model.path

parameter_overlays

extensions

assemblies