やってみた 2026年11月9日

MuJoCo 4.0.0 を移行前に試したら、pip の上書き更新は「成功」のまま import が壊れ、3mm の壁のすり抜けは1行で止まりました

XECIN C++Python物理シミュレーションMuJoCo

GitHubのトレンドに google-deepmind/mujoco が載っていました。Daily の4位で、スターは16,710、その日だけで579増えています。ロボットや機械学習の分野でよく使われる物理エンジンで、ライセンスは Apache-2.0。トレンドに上がった理由はすぐに分かりました。11月6日に 4.0.0 が出ていたんですよね。3.0 以来のメジャーバージョンです。

仕事柄、メジャーバージョンが出ると「上げて大丈夫か」を聞かれる側にいます。

教科書的な変更管理なら、まずリリースノートから影響範囲を洗い出して、影響分析の表を作るところです。ただ、4.0.0 のリリースノートは番号付きの項目だけで61あり、「Breaking changes」の囲みもエンジン・変形体・コンパイラ・サンプルの4か所にあります。フレームワークは目的ではなく手段なので、全部を表にするより、手元で困りそうなものを実際に回したほうが早い。そう考えて、今回は次の3つに絞りました(ここがテーラリングの判断です)。

  • 入れ替え手順: Python パッケージが3つに分かれた。いつもの pip install -U で上がるのか
  • 新機能: 速い物体が薄い障害物をすり抜けるのを防ぐ speculative という設定
  • 結果が変わると明記された変更: RK4 積分器の、ボールジョイントとフリージョイントの姿勢の計算

変形体(flex)まわりの破壊的変更も多いのですが、私の周りで使っている例が少ないので今回は外しています。

試した環境

Windows の Docker Desktop で python:3.12-bookworm の使い捨てコンテナを立て、その中だけで作業しました。Python 3.12.13、pip 25.0.1、numpy 2.5.4、GPU なしの CPU だけです。MuJoCo は PyPI の 4.0.0 と、比較用に1つ前の 3.17.0(10月22日公開)を、それぞれ別の venv に入れています。同梱の見本モデルは、4.0.0 のタグ(コミット ac60eae)から model/speculative/ だけを取り出しました。コンテナを立ててから捨てるまでは4分22秒でした。

まずは入れ方から

4.0.0 から、Python の配布が mujoco-core(C ライブラリと最小限のバインディング。依存は numpy だけ)、mujoco-studio(Studio とレンダラー)、mujoco(両方を入れる既定のパッケージ)の3つに分かれています。それぞれ空の venv に入れて比べました。

入れ方所要時間site-packages入ったもの・使えたもの
pip install mujoco==4.0.06.4秒182MBmujoco・mujoco-core・mujoco-studio 4.0.0、glfw 2.11.0、PyOpenGL 3.1.10、numpy 2.5.4
pip install mujoco-core==4.0.02.2秒113MBnumpy だけが付いてくる。100ステップのシミュレーションは動き、Renderer と rollout も import できる。mujoco.viewer は「glfw が要る」と ImportError
pip install mujoco==3.17.0(比較)-196MB分割前の1パッケージ

画面を出さずに計算だけ回す用途(CI や学習ジョブ)なら、core だけで70MB近く軽くなります。ちなみに既定の mujoco にはマニュアルの rst が45本と、AIエージェント向けの skill の md が8本同梱されていました。リリースノートの項目40にもそう書かれています。

いつもの手順で上げたら、成功表示のまま壊れた

ここが今回いちばんの収穫で、同時に失敗談です。

3.17.0 が入った venv に対して、普段の手順どおり pip install -U mujoco を実行しました。1秒もかからずに終わり、終了コードは0、表示は「Successfully installed」。ところが次の import mujoco で落ちます。

$ pip install -U mujoco
  Attempting uninstall: mujoco
    Uninstalling mujoco-3.17.0:
      Successfully uninstalled mujoco-3.17.0
Successfully installed mujoco-4.0.0 mujoco-core-4.0.0 mujoco-studio-4.0.0
# 終了コード 0。pip list にも 3つとも 4.0.0 で並ぶ

$ python -c "import mujoco"
ImportError: The 'mujoco' package is installed, but its core bindings ('mujoco-core') are missing or corrupted (for example, after uninstalling a previous monolithic 'mujoco' package). Repair your environment with:
  pip install --force-reinstall --no-deps mujoco mujoco-core mujoco-studio
# 終了コード 1

$ pip check
No broken requirements found.
# 終了コード 0(依存関係の検査は通ってしまう)

# 表示どおりに直す
$ pip install --force-reinstall --no-deps mujoco mujoco-core mujoco-studio
$ python -c "import mujoco; print(mujoco.__version__)"
4.0.0

壊れた状態では site-packages/mujoco/ の下のファイルが150個(.so は4個)しかなく、直したあとは384個(.so は19個)になりました。リリースノートの項目3には「分割前の mujoco から pip で上げるときは、先に uninstall するか、上げたあとに —force-reinstall —no-deps を実行すること。そうしないと mujoco-core に移ったファイルを pip が消してしまう」とちゃんと書かれています。つまり教科書には書いてあって、私の手順のほうが古かったわけです。

正直なところ、エラーメッセージが直し方まで教えてくれるのはかなり親切だと思います。怖いのは、pip install も pip check も成功を返すので、更新処理の終了コードだけを見ている CI やセットアップスクリプトは素通りすることです。現場では、更新のあとに python -c "import mujoco" を1行足しておくのが安上がりな保険になります。

3mm の壁と、すり抜けない設定

次は新機能です。薄い物体を速い物体が1ステップで飛び越えてしまう「すり抜け(トンネリング)」を防ぐ、speculative という有効化フラグが入りました。自分で作った最小のモデルで試しています。

<mujoco>
  <option timestep="0.004" gravity="0 0 0">
    <flag speculative="enable"/>  <!-- 4.0.0 で追加。この行を消すと既定(無効) -->
  </option>
  <worldbody>
    <!-- 厚さ3mm の壁(x=0.5) -->
    <geom name="wall" type="box" pos="0.5 0 0" size="0.0015 0.2 0.2"/>
    <body name="ball" pos="0 0 0">
      <freejoint/>
      <!-- 半径1cm の鋼球。x 方向に初速を与えて壁に当てる -->
      <geom name="b" type="sphere" size="0.01" density="7800"/>
    </body>
  </worldbody>
</mujoco>

剛体1個と壁1枚だけの、いちばん単純な構成です。接触がたくさんあるモデルでの効き方や重さは別物だと思うので、ここは自分の使い方次第で測り直しが要るところです。

初速を変えて、球が最後に壁の手前に残ったか、向こう側へ抜けたかを見ました。時間刻みは 4ms です。

初速既定(フラグなし)speculative=“enable”
1 m/s止まる(跳ね返り速度 -0.140 m/s)止まる(跳ね返り速度 -0.018 m/s)
3 m/s抜ける(0.953 m/s まで減速して通過)止まる
5〜100 m/s抜ける(速度はほぼ落ちない)止まる(球の中心は x=0.4872〜0.4884 m=壁の面に接した位置)

既定のままだと、1ステップで進む距離が 12mm しかない 3 m/s でも抜けてしまいます。接触自体は検出されている(接触数が1になる)のに、押し戻しきれずに向こう側へ出ていく。フラグを入れると、100 m/s でも壁の面で止まりました。既定の挙動は、比べた速さでは 3.17.0 と 4.0.0 で数字まで同じだったので、「4.0.0 にしたら何かが変わる」わけではなく、選べる手段が増えた、という理解で良さそうです。

従来の定石は「時間刻みを小さくする」ですが、こちらも試しました。初速 20 m/s での結果です。

# 時間刻みを小さくする(フラグなし)
dt=0.004   -> 抜ける  x=+5.0400 vx=+20.000
dt=0.001   -> 抜ける  x=+2.0000 vx=+20.000
dt=0.0005  -> 抜ける  x=+1.4012 vx=+18.034
dt=0.00025 -> 抜ける  x=+1.1943 vx=+18.525
# フラグあり
dt=0.004   -> 止まる  x=+0.4876 vx=-0.006

# 1秒分を計算するのにかかった時間(5回のうち最速)
dt=0.004   フラグなし   250ステップ  0.26ms  (抜ける)
dt=0.004   フラグあり   250ステップ  0.30ms  (止まる)
dt=0.0005  フラグなし  2000ステップ  2.15ms  (抜ける)
dt=0.00025 フラグなし  4000ステップ  4.28ms  (抜ける)

刻みを16分の1にして計算時間が約16倍になっても、この条件では抜けました。フラグのほうは、この単純なモデルでは 0.26ms が 0.30ms になった程度です。

一方で、気になる差も出ました。上の表の 1 m/s の行です。すり抜けが起きない遅さでも、フラグを入れると跳ね返りの速さが -0.140 から -0.018 m/s に変わりました。同梱の見本の README には、衝突を2ステップに分けて扱うことや、ほぼ弾性の衝突を作るときの設定の注意が書かれていて、この差はそこに関係していそうです(中身までは追えていないので、ここは推測です)。跳ね返りが大事なモデルでは、全体に一律でオンにする前に確かめたほうが良さそうです。

同梱の見本でも同じことが起きる

4.0.0 には、このフラグを見せるための見本モデルが3つ同梱されています。そのうち、厚さ3mm の鋼板を5枚吊るしたニュートンのゆりかご(newton.xml、時間刻み 4ms)を、見本のまま(有効)と、フラグを disable に書き換えたものとで3秒ずつ回し、板の並び順が入れ替わった回数を数えました。有効のままだと0回、無効にすると最大3回で、最初の入れ替わりは 0.552秒でした。

同じ時刻を 4.0.0 のレンダラーで画像にしたのが次の図です(コンテナ内で OSMesa を使って描き、4コマを並べて見出しと時刻を書き足しています)。

ニュートンのゆりかごの見本 newton.xml を、上段は speculative 有効、下段は無効で、t=0.500、0.552、0.600、0.700 秒の4コマずつ並べた図。上段では赤い板1が当たり、0.600秒で右端の青い板5が振り出される。下段では赤い板1が白い板の間に入り込み、0.600秒には青い板5ではなく灰色の板4が振り出されている

上段は見本どおりで、左から来た赤い板1が当たると、右端の青い板5が振り出されます(0.700秒の位置は 436mm)。下段のフラグなしでは、赤い板1が板2と板3をすり抜けて板3と板4の間まで入り込み、振り出されるのは青い板5ではなく灰色の板4のほうです。板4は板5を抜けて外へ出ていきます。数字で見ていたときより、絵にしたほうが「何が起きているか」が一目で伝わりますね。

もう1つ、移行で効いてくる点があります。この見本を 3.17.0 で開こうとすると、読み込みの段階で失敗します。

ValueError: XML Error: Schema violation: unrecognized attribute: 'speculative'
Element 'flag', line 18

speculative="enable" の属性を外せば 3.17.0 でも読めました。チームの中で 3 系と 4.0 が混ざる期間にモデルの XML を共有するなら、このフラグは片側にしか書けない、ということになります。

RK4 の姿勢の精度は、本当に2次から4次になっていた

リリースノートの項目5には「RK4 積分器が、ボールジョイントとフリージョイントの姿勢について4次精度になった。以前は2次でしか収束していなかった。RK4 でこれらの関節を使うモデルはシミュレーション結果が変わる」とあります。結果が変わると言われたら、どれくらい変わるのかを測っておきたいところです。

重力も接触もない空間で、直方体を1つ回転させました。同じ版の時間刻み 0.0001秒の結果を基準にして、時間刻みを半分ずつにしたときの姿勢(クォータニオン)のずれを比べています。4次なら半分にするたびに誤差が16分の1、2次なら4分の1になるはずです。

# 3.17.0(integrator="RK4"、2秒後の姿勢のずれ)
dt=0.04    1.234e-04
dt=0.02    3.084e-05   前の刻みとの比  4.00(2次)
dt=0.01    7.707e-06   前の刻みとの比  4.00(2次)
dt=0.005   1.926e-06   前の刻みとの比  4.00(2次)
dt=0.0025  4.810e-07   前の刻みとの比  4.00(2次)

# 4.0.0(同じモデル・同じコード)
dt=0.04    1.983e-07
dt=0.02    1.249e-08   前の刻みとの比 15.87(3.99次)
dt=0.01    7.833e-10   前の刻みとの比 15.94(3.99次)
dt=0.005   4.904e-11   前の刻みとの比 15.97(4.00次)
dt=0.0025  3.071e-12   前の刻みとの比 15.97(4.00次)

きれいに2次と4次に分かれました。時間刻み 0.01秒で比べると、ずれは 7.7×10⁻⁶ から 7.8×10⁻¹⁰ へ、約1万分の1です。精度が上がるのは良いことなのですが、裏を返すと、3 系で保存しておいた軌跡を「正解データ」にして回帰テストをしているなら、4.0 ではその比較が合わなくなるということでもあります。移行作業の見積もりに、正解データの作り直しを入れておく必要があります。

今思えば、最初はずれを角度(acos)で測ろうとして、4.0.0 の誤差が小さすぎて0に丸まり、比を計算するところでゼロ除算になりました。精度の比較で比較の道具のほうが先に音を上げたわけで、ここは苦笑いでした。クォータニオンの差の大きさで測り直して上の数字になっています。

試してみての所感

今回分かったことを、移行判断のチェックリストにするとこうなります。

確認項目実際に起きたこと私ならこうする
3.17.0 からの pip 更新pip install -U は終了コード0、pip check も通るが import mujoco が ImportErrorvenv を作り直すか、先に pip uninstall -y mujoco。更新後に import の確認を1行足す
画面なしの用途mujoco-core だけで 113MB(既定は 182MB)。シミュレーションは動き、Renderer も import できるCI や学習ジョブは core に寄せる
speculative3mm の壁を 100 m/s まで止める。時間刻みを16分の1にしても止まらなかった条件でも止まる。ただし遅い衝突の跳ね返りが変わる薄い物体と速い物体があるモデルだけで有効化し、跳ね返りを見て判断
XML の互換speculative の属性があると 3.17.0 では読み込みエラー3 系と共有するモデルには当面書かない
RK4 の結果姿勢の誤差が2次から4次に。dt=0.01 で約1万分の1正解データの作り直しを移行作業に含める

新しく始めるものは 4.0 で問題ないと思います。既存の環境は、上書き更新ではなく venv の作り直しで上げるつもりです。ぶっちゃけ、今回いちばん効いたのは新機能より「成功表示のまま壊れる」を手元で一度踏めたことで、これは自分の手順メモにそのまま反映できます。

様子見なのは speculative を全体に効かせることです。跳ね返りの違いと、接触の多いモデルでの重さは、自分たちのモデルで測ってから決めます。変形体まわりの破壊的変更と、JAX で書かれた MJX は今回まったく触れていないので、そこは別の機会に。