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.0 | 6.4秒 | 182MB | mujoco・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.0 | 2.2秒 | 113MB | numpy だけが付いてくる。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コマを並べて見出しと時刻を書き足しています)。

上段は見本どおりで、左から来た赤い板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 が ImportError | venv を作り直すか、先に pip uninstall -y mujoco。更新後に import の確認を1行足す |
| 画面なしの用途 | mujoco-core だけで 113MB(既定は 182MB)。シミュレーションは動き、Renderer も import できる | CI や学習ジョブは core に寄せる |
| speculative | 3mm の壁を 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 は今回まったく触れていないので、そこは別の機会に。