再現可能な parameter experiment

fibril_sim experiment は、一つの canonical simulation model に対して明示的な parameter variant を実行します。 MJCF を複製すると、どの scalar change が結果を変えたのか追いにくくなるため、tuning と regression investigation では parameter experiment を使います。

Experiment の contract

一つの experiment は次の要素で構成します。

1. 一つの canonical SimulationManifest と、それが参照する一つの canonical MJCF model
2. 任意の scenario override
3. tunable parameter ID と typed target を定義する既存の Fibril parameter-overlay artifact
4. 明示的な baseline と、0 個以上の明示的な variant
5. execution setting
6. trace から導出する generic metric definition

experiment schema は parameter target syntax を複製しません。 variant は baseline overlay で既に宣言された ID の parameter_values だけを置き換えます。 canonical SimulationManifest が参照する固定 overlay はそのまま有効で、通常の construction provenance も保持されます。

parameter-overlay schema 1.1 では、typed range target に 2 要素の numeric sequence も指定できます。 physical range / constraint experiment で利用できる generic MuJoCo target は次の通りです。

Target	Value	検証と適用
mujoco:tendon_range:<name>	[min, max]	有限値を 2 個指定し、min <= max を満たす必要があります。named tendon の mjSpec range を変更します。
mujoco:joint_range:<name>	[lower, upper]	有限値を 2 個指定し、lower <= upper を満たす必要があります。named joint は hinge または slide である必要があり、authored limited semantics は変更せず mjSpec range だけを変更します。
mujoco:equality_weld_torquescale:<name>:0	scalar	有限かつ非負である必要があります。named equality は weld である必要があり、mjSpec の weld torquescale field を変更します。
mujoco:plugin_attribute:<instance>:<attribute>	scalar	有限値である必要があります。compile 前に named MuJoCo plugin instance の attribute を一つ更新します。attribute の semantics と validation は plugin 側が所有します。

未知の name、不正な MuJoCo object type、不正な value count、非有限値、逆転した range は construction 中に失敗します。 range value は対応する MJCF attribute の semantics と unit をそのまま使います。 overlay は limited flag や default class を推論して書き換えません。

schema_version: {major: 1, minor: 0}
id: wheel-damping-study
model:
  manifest: simulation.yaml
scenario: pickup-start.yaml
parameters:
  baseline_overlay: damping-baseline.yaml
variants:
  - id: damping-001
    parameter_values: {wheel_damping: 0.01}
  - id: damping-005
    parameter_values: {wheel_damping: 0.05}
metrics:
  - id: chassis_displacement
    kind: signal
    signal: body:chassis.position
    reduce: delta_norm
  - id: peak_motor_force
    kind: signal
    signal: actuator:drive.force
    reduce: max_abs
  - id: contact_time
    kind: contact_duration
    contact: pickup_surface
  - id: realtime_factor
    kind: rtf
assertions:
  - metric: chassis_displacement
    op: lt
    value: 0.20
execution:
  steps: 2000
  timeout_seconds: 10.0
  workers: 1
  cpu_budget: 4
  mujoco_internal_threads: 1

variants は意図的に明示的な list としています。 runner は暗黙の Cartesian product を生成しません。 すべての組み合わせを意図して実行する場合だけ、runner の外側で明示的な matrix を生成してください。

Metric の定義

signal metric は fibril_sim trace query と同じ semantic selector namespace を使います。

• body:<name>.position
• body:<name>.quaternion
• joint:<name>.position
• joint:<name>.velocity
• sensor:<name>
• actuator:<endpoint>.applied
• actuator:<endpoint>.force

signal reducer は現在 final、max_abs、max_norm、delta_norm、duration_above（threshold を指定）を利用できます。 そのほかの generic metric kind は contact_duration、max_contact_wrench、event_reached、rtf です。

metric は generic contract に留めます。 robot または task 固有の name と threshold は Fibril core code ではなく experiment manifest に置きます。

実行と CPU ownership

correctness を優先し、既定では直列実行（workers: 1）です。 variant-level parallelism は明示的に有効化できます。 workers は cpu_budget 以下である必要があります。 最初の schema では mujoco_internal_threads: 1 が必須なので、並列化されるのは variant level だけで、nested oversubscription は発生しません。 calibration の parallelism はこの runner の責務外です。

Failure semantics の扱い

一つの不正な variant が sibling variant の実行を中断することはありません。 run result は status、success、error_reason を記録します。 result class には、不正な parameter ID / type、model / overlay compile failure、runtime / numerical failure、timeout、利用不能な metric、assertion failure があります。

Result manifest の内容

experiment run は、experiment / source hash、canonical manifest path、scenario、baseline overlay path / hash、MuJoCo version、execution setting、順序付き run record、baseline comparison を含む versioned JSON document を出力します。 成功した各 run は MCAP trace を参照し、construction provenance と source hash を含む resolved SimulationPlan inspection document も埋め込みます。

run record には、完全な parameter value、resolved typed target provenance、baseline-relative parameter diff、timestamp、metric、assertion outcome、trace reference、必要に応じた error reason が含まれます。 comparison section には baseline / variant の success、parameter diff、metric diff、trace reference が含まれます。

CLI

fibril_sim experiment run experiment.yaml --output results.json

複製した diagnostic MJCF から移行する

たとえば robot_diag_damping_001.xml、robot_diag_damping_005.xml、robot_diag_damping_010.xml が robot.xml と一つの joint damping scalar だけ異なる場合を考えます。 robot.xml を canonical model として残し、target が mujoco:joint_damping:<joint>:0 の既存 schema overlay を一つ作ります。 現在の production value を baseline value とし、0.01 / 0.05 / 0.10 を明示的な experiment variant として表現します。 scenario と metric は experiment manifest に置きます。 結果が diagnostic run を再現できたら、variant 生成器を追加するのではなく複製した MJCF を削除します。

robot または task 固有の metric name、event、acceptance threshold、field layout、parameter ID を Fibril 側へ移してはいけません。 Fibril が所有するのは generic な experiment、overlay、trace、metric、result contract だけです。