Skip to content

MuJoCo と Fibril

Fibril Simulation を使うときは、MuJoCo が担当する物理モデルと Fibril が担当する virtual hardware の境界を先に決めます。 同じ設定を MJCF と Manifest の両方へ重複して書くと、どちらが simulation contract を持つのかが曖昧になるためです。

所有先は「Fibril を外して mj_step() だけを実行したときにも運動または力が変わるか」で判断します。 変わる parameter は MJCF が所有し、controller が見る値の単位、取得周期、transport、noise、timeout だけを変える parameter は Fibril が所有します。 実機完成後に同定した parameter は、この所有先を変えずに calibration overlay として nominal model を補正します。

再利用単位

再利用する設定は一種類の profile に集約しません。 物理モデルと virtual-device semantics は実行時の意味が異なるため、次の単位に分けます。

  • MJCF model preset：motor の R/K/L など、複数機体で再利用できる physical default class です。
  • MJCF model module：body、joint、site、sensor、actuator を一体で再利用する submodel です。
  • Component profile：device output convention、transport cadence、residual noise など Fibril 側の reusable config です。
  • Calibration overlay：nominal MJCF または effective Component config に後から適用する同定値です。

Component profile は device、transport、empirical などの facet を合成できます。 physical motor parameter を Component profile に複製して facet 合成する構成にはしません。

MuJoCo が定義するもの

MuJoCo model は、物理計算に必要な構造と object を定義します。 Fibril の標準 Component で頻繁に参照する object は次のとおりです。

  • body：剛体の階層と pose を持つ単位です。
  • joint：body 間の自由度を定義します。
  • geom：collision、contact、mass などに使う geometry です。
  • site：body に固定された名前付き frame であり、MuJoCo sensor や planar LiDAR の pose を指定するときに使います。
  • actuator：MuJoCo model に力や制御入力を与える endpoint です。
  • sensor：MuJoCo が計算した sensor data を sensordata に出力します。
  • camera：視点と projection を定義します。

Fibril Simulation はこれらの object name を compile 時に解決します。 Manifest に存在しない object name を指定した場合は、run 中まで持ち越さず Plan construction を失敗させます。

Fibril が追加するもの

Fibril の Component は、MuJoCo object の上に hardware-like semantics を追加します。 代表的な semantics は acquisition period、transport latency、quantization、noise、timeout、safe value、controller-visible delivery です。

たとえば MuJoCo の site は「距離センサー」そのものではありません。 MuJoCo の native rangefinder sensor が幾何学的な距離を生成し、fibril_sim/rangefinder はその sensor 値に bias、noise、resolution、latency などの仮想ハードウェア特性を適用します。

Sensor と rangefinder

次の MJCF は site を measurement frame として native rangefinder sensor を定義します。 MuJoCo rangefinder は site の +Z 方向へ ray を飛ばします。

1
2
3
4
5
6
<body name="sensor_body" pos="0 0 0.5">
  <site name="front_rangefinder" pos="0 0 0" zaxis="1 0 0"/>
</body>
<sensor>
  <rangefinder name="front_rangefinder_sensor" site="front_rangefinder"/>
</sensor>

Manifest は site ではなく native sensor 名を参照します。

1
2
3
4
5
6
7
8
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

ray cast と自己 body の除外は MuJoCo native rangefinder が担当します。 Fibril はその sensordata を raw source として読みます。

Joint と encoder

fibril_sim/encoder は MuJoCo の hinge joint を参照します。 Fibril は joint position を読み、direction、zero、offset、noise、encoder count resolution を適用して encoder sample を作ります。

1
2
3
4
5
6
7
components:
  - id: steering_encoder
    type: fibril_sim/encoder
    config:
      joint: steering_joint
      counts_per_revolution: 4096
      period_s: 0.001

この Component は hinge joint を前提とします。 slide joint の position を encoder として扱う場合は、現在の標準 fibril_sim/encoder の contract には含まれません。

MuJoCo sensor と IMU

fibril_sim/imu は MuJoCo の sensor object を入力として使います。 gyroscope と accelerometer は必須で、orientation sensor は任意です。

1
2
3
4
<sensor>
  <gyro name="imu_gyro" site="imu_site"/>
  <accelerometer name="imu_accel" site="imu_site"/>
</sensor>

1
2
3
4
5
6
7
components:
  - id: imu
    type: fibril_sim/imu
    config:
      gyroscope_sensor: imu_gyro
      accelerometer_sensor: imu_accel
      period_s: 0.005

Fibril は MuJoCo が計算した raw sensor value に bias、noise、resolution、latency を重ねます。 sensor physics を Fibril 側で再実装する構成ではありません。

Actuator と virtual driver

fibril_sim/scalar_actuator と fibril_sim/motor は MuJoCo actuator を参照します。 fibril_sim/motor では servo gain、force limit、motor dynamics を MJCF に置き、Fibril 側は command latency、application schedule、timeout、logical encoder、feedback delivery を担当します。

たとえば position motor は MuJoCo native <position> actuator で kp、kv、forcerange を定義します。 Fibril はその actuator へ logical motor command を渡し、feedback の applied effort は MuJoCo の actuator_force から取得します。

標準の physical motor preset は package://fibril_sim_models/mujoco/actuator_presets.xml から include できます。 一方、motor Component profile は controller-visible current convention などの interface semantics を提供します。 physical current/torque model と driver が報告する current convention は一致するとは限らないため、両者を同じ source of truth に統合しません。

Prescribed state と mocap body

fibril_sim/prescribed_pose と fibril_sim/prescribed_trajectory は one-way の prescribed motion を表します。 対象 body は MuJoCo の mocap body として解決できる必要があります。

prescribed motion は dynamic body の pose を毎 step 無条件に書き換える仕組みではありません。 Fibril は continuous authority として扱い、接続された dynamic body が prescribed motion へ物理的に反応できる境界を保ちます。

Physics timestep の所在

physics timestep は MJCF の <option timestep="..."> が source of truth です。 Fibril は compile 済み mjModel.opt.timestep を SimDuration に変換し、Device、prescribed state、actuator application などの schedule をその fixed physics grid に対して検証します。

MuJoCo の solver parameter、contact parameter、material parameter などは MJCF 側で管理します。 Fibril docs は MuJoCo の XML reference を置き換えないため、MJCF の詳細は MuJoCo の公式 documentation を参照してください。