A C++ Environment That Matches Python to the BitPythonとビット単位で一致するC++環境

Reinforcement learning trains a policy by letting it act in a simulator millions of times. To do that quickly you run many copies of the simulated robot at once and feed the policy a batch of observations per step. The object that holds those copies and steps them together is called a vector environment.

強化学習では、シミュレータ内でpolicyに何百万回も行動させて学習します。これを速く回すには、シミュレーション上のロボットを多数同時に動かし、 1 stepごとにobservationをバッチでpolicyに渡します。この複数のコピーを保持してまとめてstepさせるものをvector environmentと呼びます。

The Microduck project has one written in Python. Python can only execute one thread of its own code at a time, so its vector environment starts eight separate processes and talks to them through pipes. That works, and every number in that project was measured on it. It also means a fixed cost per step that has nothing to do with physics: serialising actions, waking eight processes, waiting for the slowest one, copying observations back.

MicroduckプロジェクトにはPythonで書いたものがあります。Pythonは自身のコードを同時に1スレッドしか実行できないため、 そのvector environmentは8つの独立したプロセスを起動し、pipeで通信します。これは正しく動き、同プロジェクトの数値はすべてこの上で計測しました。 一方で、物理計算とは無関係な固定コストが毎stepかかります。actionのシリアライズ、8プロセスの起床、最も遅いプロセスの待ち、observationの書き戻しです。

This repository is the same environment in C++. The step loop has no interpreter in it, so eight environments run on eight threads of one process and share memory. A small binding lets Python call it, and the Microduck training script runs on it with no edits.

このリポジトリは同じ環境をC++で実装したものです。stepループにインタプリタが介在しないため、8つの環境が1プロセス内の8スレッドで動き、メモリを共有します。 小さなbindingでPythonから呼び出せるようにしてあり、Microduckの学習スクリプトは無修正で動きます。

Getting there meant matching how numpy adds fourteen numbers, how Python squares a float, and how a float32 constant is promoted to float64. Those three details are the middle of this page. The throughput numbers are at the end, with their caveats, because they turned out to say something about the Python environment too.

そのためには、numpyが14個の数をどう足すか、Pythonがfloatをどう2乗するか、float32の定数がどうfloat64に昇格されるかを合わせる必要がありました。 この3点がページの中盤です。throughputの数値は注意点とあわせて最後に置いています。結果的にPython環境についても分かったことがあったためです。

The Python project left two measurements it could not explain from inside Python. First, its environment wrapper cost 25% over bare physics on one core. Second, scaling across eight processes settled at 55% efficiency on one robot model and 42% on the one actually used for training, and the loss was attributed to a shared resource outside the cores, without proof. Whether process isolation itself was part of the loss was unknowable without an implementation that did not use processes.

Pythonプロジェクトには、Pythonの中からは説明できない計測結果が2つ残っていました。1つ目は、1コアで環境wrapperが物理計算単体より25%余計にかかっていたこと。 2つ目は、8プロセスへのスケーリング効率が、あるロボットモデルで55%、実際に学習に使ったモデルで42%にとどまったことです。 この損失はコア外の共有リソースによるものとしていましたが、証明はありませんでした。プロセス分離そのものが損失の一部かどうかは、プロセスを使わない実装がなければ分かりません。

A C++ version answers both, but only if it is the same environment. The order of work therefore was: port the environment, prove equality, and only then run the benchmarks. Timing code that has not been proven equal produces a number about a different environment.

C++版なら両方に答えられますが、それは同じ環境である場合に限ります。そのため作業順は、環境を移植し、一致を証明し、その後で初めてベンチマークを取る、としました。 一致が証明されていないコードの時間を測っても、それは別の環境についての数値にすぎません。

Everything measured in the Python project was measured inside a budget of eight of the machine's fourteen cores. This repo inherits that rule in code: VecEnv refuses more than eight threads unless the caller passes allow_overcommit.

Pythonプロジェクトの計測はすべて、マシンの14コアのうち8コアという枠内で行いました。このリポジトリはそのルールをコードとして引き継いでいます。 呼び出し側がallow_overcommitを渡さない限り、VecEnvは8を超えるスレッド数を拒否します。

The Python environment gets its randomness from numpy: initial joint noise, then which control steps the pushes land on (a draw without replacement), their speeds and directions, and under domain randomisation the servo parameters, mass, friction, latency and noise. Reproducing that draw in C++ would mean reimplementing numpy's seed-sequence expansion, its choice and its ziggurat normal sampler, and getting all three right. It is possible. It is also beside the point, because the draw is not what the environment does; it is what the environment is handed.

Python環境の乱数はnumpyから来ます。関節の初期ノイズ、pushが入る制御step（非復元抽出）、pushの速度と方向、 そしてdomain randomisation時のサーボパラメータ・質量・摩擦・latency・ノイズです。この抽選をC++で再現するには、numpyのseed-sequence展開、 choice、ziggurat法の正規分布サンプラーを再実装し、3つすべてを正確に合わせる必要があります。不可能ではありません。 しかし本題から外れます。抽選は環境が行う処理ではなく、環境に渡される入力だからです。

So the test runs the Python environment, reads what it drew, and passes those values to the C++ environment through EpisodeParams: the post-noise joint state, the push schedule, and the DR factors if any. From that moment the two environments share every line of logic and receive the same 250 actions.

そこでテストではPython環境を実行して抽選結果を読み取り、その値をEpisodeParams経由でC++環境に渡します。 渡すのはノイズ適用後の関節状態、pushスケジュール、そしてあればDRの係数です。この時点から2つの環境はすべてのロジックを共有し、同じ250個のactionを受け取ります。

pe = MicroduckEnv(seed=s, **kw); o_py = pe.reset(seed=s)
params = vecenv_cpp.episode_params(pe.data.qpos[qi], pe.data.qvel[vi],
                                   pe._push_at, pe._push_vel, dr=pe.dr.current)
ce = vecenv_cpp.Env(make_config(**kw), s); o_cpp = ce.reset(params)
# 250 identical actions into both; compare obs, reward, terms, flags, info

Env::reset(const EpisodeParams&) is that entry point. Env::reset() with no argument uses the environment's own PCG64 and is what training uses.

その入口がEnv::reset(const EpisodeParams&)です。引数なしのEnv::reset()は環境自身のPCG64を使い、学習ではこちらを使います。

Result結果

The 25 episodes cover both reward versions, action latency 0 and 2, initial noise 0 and 0.02, an action scale of 0.5 with five pushes, the two held-out physics variants (35 and 25 position coordinates, with strided joint indices), and two DR cases with injected factors. Every observation is the same float32 array, every reward the same float64, and pushed, fallen, t, truncated, terminated, trunk_height and upright_cos agree on every step. The pytest suite asserts this at 1e-6 on observations and 1e-9 relative on rewards, so a last-bit difference in a system library would pass while a real defect would not; the report script counts exact matches separately so the distinction stays visible. One further test shifts a single push by one step and checks that the comparison notices.

25 episodesは、rewardの両バージョン、action latency 0と2、初期ノイズ0と0.02、push 5回でaction scale 0.5の条件、 held-outの物理variant 2種（位置座標35個と25個、関節インデックスは飛び飛び）、係数を注入したDRケース2つをカバーしています。 すべてのobservationが同じfloat32配列、すべてのrewardが同じfloat64で、pushed、fallen、t、 truncated、terminated、trunk_height、upright_cosも毎stepで一致します。 pytestスイートではobservationを1e-6、rewardを相対1e-9で判定しています。システムライブラリによる最終ビットの差は通し、本物の不具合は通さないためです。 レポートスクリプトは完全一致を別に数えるので、この区別は見えたまま残ります。さらに、pushを1つだけ1 stepずらし、比較がそれを検出することを確かめるテストもあります。

one model per env環境ごとに1モデル

Domain randomisation writes into mjModel (damping, gains, masses, friction). A shared model would make DR a data race and every environment identical. Env takes a prototype and mj_copyModels it. A test mutates one environment's masses and checks the prototype and its neighbours are untouched. Sixteen bodies and 82 geoms: the copies are kilobytes.

Domain randomisationはmjModel（減衰、ゲイン、質量、摩擦）に書き込みます。モデルを共有すると、DRはデータ競合になり、全環境が同一になってしまいます。 Envはプロトタイプを受け取り、mj_copyModelでコピーします。1つの環境の質量を書き換え、プロトタイプと他の環境が変わっていないことを確かめるテストがあります。 body 16個・geom 82個なので、コピーは数KBです。

env i on thread i mod Tenv iをスレッドi mod Tに

Always. So the assignment of environments to threads is fixed, and the result does not depend on T. A test runs the same 300 steps on 1, 2 and 4 threads and compares observations, rewards, dones and terminal observations with ==; another runs 260 steps as three sequential Envs, autoreset included, and gets the same bits.

常にこの割り当てです。環境とスレッドの対応が固定されるため、結果はTに依存しません。 同じ300 stepを1・2・4スレッドで実行し、observation、reward、done、terminal observationを==で比較するテストがあります。 別のテストでは260 stepを3つのEnvの逐次実行（autoreset含む）として回し、同じビットが得られることを確認しています。

generation countergenerationカウンタ

The caller writes the action batch, increments an atomic counter and works as thread 0. The other T−1 threads spin on the counter for tens of microseconds and then block on a condition variable. While the policy is computing its next action the pool burns nothing; while it is stepping, there is no futex call per step. Acquire and release ordering on the counter and on the completion count is what makes the action and observation buffers visible without a lock.

呼び出し側がactionのバッチを書き込み、atomicカウンタを1つ進め、自身もスレッド0として働きます。残りのT−1スレッドは数十マイクロ秒カウンタをspinで監視し、 その後condition variableでblockします。policyが次のactionを計算している間、スレッドプールはCPUを消費しません。stepを回している間は、stepごとのfutex呼び出しもありません。 カウンタと完了カウントに対するacquire/releaseのメモリ順序によって、ロックなしでactionとobservationのバッファが見えるようになっています。

autoreset

Matches the Python version: when an episode ends, the observation returned is the new episode's first, and the ended episode's final observation is kept in terminal_obs. Every episode here ends on the step limit, never on a terminal state, so the training loop bootstraps V(terminal_obs); the flags are carried so a stock advantage estimator cannot get this wrong silently.

Python版と同じ挙動です。episodeが終わると、返されるobservationは新しいepisodeの最初のもので、終わったepisodeの最後のobservationはterminal_obsに保持されます。 ここではすべてのepisodeが終端状態ではなくstep上限で終わるため、学習ループはV(terminal_obs)でbootstrapします。 フラグも一緒に渡しているので、標準的なadvantage推定器がここを黙って間違えることはありません。

the budgetスレッド上限

More than eight threads is refused unless the caller says allow_overcommit. Every number in the Python project was taken inside eight of fourteen cores on a laptop with other work to do, and this repo inherits that as a constructor check rather than a comment.

呼び出し側がallow_overcommitを指定しない限り、8を超えるスレッド数は拒否されます。Pythonプロジェクトの数値はすべて、 他の作業もするノートPCの14コア中8コアの枠内で取ったものです。このリポジトリはそれをコメントではなくコンストラクタのチェックとして引き継いでいます。

CI runs three jobs on every push. The first builds Release, runs the 34 C++ cases, the 41 Python tests and the equality report against the Python repository at a pinned commit, after fetching the robot assets from their upstream (they are Creative Commons BY-SA-NC and are never committed). The second and third rebuild the C++ suite under -fsanitize=address,undefined and under -fsanitize=thread. The thread-count independence test is the one ThreadSanitizer exists for: a race on the shared action or observation buffers would fail the build.

CIはpushごとに3つのジョブを実行します。1つ目はロボットのアセットをupstreamから取得したうえで（Creative Commons BY-SA-NCのためコミットしません）、 Releaseビルドを行い、C++ 34ケース、Python 41テスト、そして固定コミットのPythonリポジトリに対する一致レポートを実行します。 2つ目と3つ目は、C++スイートを-fsanitize=address,undefinedと-fsanitize=threadでそれぞれ再ビルドします。 ThreadSanitizerが本領を発揮するのはスレッド数非依存のテストで、共有されたactionやobservationのバッファで競合があればビルドが失敗します。

The C++ side links the same libmujoco.so that the Python side imports: CMake asks the Python interpreter where the wheel lives and takes the headers and library from there, so nothing is installed system-wide. check_library_version() refuses to run if the header and the library disagree. The equality claim is only meaningful against the same physics binary.

C++側は、Python側がimportするのと同じlibmujoco.soをリンクします。CMakeがPythonインタプリタにwheelの場所を問い合わせ、 そこからヘッダとライブラリを取るので、システム全体には何もインストールしません。ヘッダとライブラリが食い違えばcheck_library_version()が実行を拒否します。 一致の主張は、同じ物理エンジンのバイナリに対してのみ意味を持つからです。

• Bit equality holds on one machine, one compiler, one C library. Python's pow and exp and the C++ ones are the same library calls on the same host, which is why they agree. A runner with a different glibc, or a numpy built with a different vectorised exp, could differ in the last bit on the height term. The test tolerances are set so that would pass and a real defect would not.
• The draw is not replicated. Same seed, different pushes. A step-by-step replay of a Python training run on the C++ backend is not available; comparisons between the two are statistical, across seeds.
• Sensor noise is not contract-tested, for the same reason: it is a Gaussian per step and the C++ draws its own. The contract cases run with it off.
• Three training seeds per backend. Enough to show the seed-0 survival gap was run-to-run spread; not enough to resolve a backend difference smaller than that spread (survival sd 0.06 to 0.14, return sd 2 to 8 over seeds).
• One robot. Env is Microduck-shaped: 14 actuators, a standing keyframe, a named trunk body, named gyro and orientation sensors. The threading layer is not, and a second model behind the same interface is the natural next step.
• No rendering. Image observations through MuJoCo's C rendering API are deferred until a machine with a working EGL context exists; the laptop this was written on has GLFW through WSLg and nothing else.
• The speed numbers are for this laptop. Fourteen cores of three kinds under a hypervisor, with a power state the guest cannot read. The ratios are more portable than the absolute rates, and the sustained band is more portable than any 20-second row.

• ビット一致は1台のマシン・1つのコンパイラ・1つのCライブラリでの話です。PythonのpowやexpとC++のそれは、 同じホスト上の同じライブラリ呼び出しなので一致します。glibcが異なるrunnerや、ベクトル化されたexpの実装が異なるnumpyでは、 高さ項の最終ビットが変わる可能性があります。テストの許容誤差は、それなら通し、本物の不具合なら通さないように設定しています。
• 乱数の抽選は再現していません。同じseedでもpushは異なります。Pythonの学習実行をC++ backend上でstepごとに再生することはできず、 両者の比較は複数seedにわたる統計的なものです。
• センサーノイズはcontractテストの対象外です。理由は同じで、stepごとのガウスノイズをC++側が独自に引くためです。contractケースではノイズをオフにしています。
• 学習seedはbackendごとに3つです。seed 0のsurvivalの差が実行ごとのばらつきだと示すには十分ですが、 そのばらつき（seed間でsurvivalのsd 0.06〜0.14、returnのsd 2〜8）より小さいbackend間の差を見分けるには足りません。
• ロボットは1種類です。EnvはMicroduck専用の形をしています。アクチュエータ14個、立位のkeyframe、名前付きの胴体body、 名前付きのジャイロと姿勢センサーです。スレッド層はそうではなく、同じインターフェースの裏に2つ目のモデルを載せるのが自然な次のステップです。
• レンダリングはありません。MuJoCoのCレンダリングAPIによる画像observationは、EGLコンテキストが動くマシンが用意できるまで保留しています。 これを書いたノートPCで使えるのはWSLg経由のGLFWだけです。
• 速度の数値はこのノートPCでのものです。ハイパーバイザ配下の3種類・14コアで、電力状態はゲストから読めません。 絶対値より比率のほうが他環境に持ち出しやすく、20秒の各行よりsustainedの幅のほうが持ち出しやすい数値です。

The Microduck balance task has a Python environment that runs eight forked processes. This is the same environment in C++17 on eight threads, with a pybind11 binding and a drop-in class so the Python training script runs on it unchanged. Before any timing, the two were made to agree to the bit: the test lets Python draw the episode's randomness and hands the drawn values to the C++ side, then feeds both 250 identical actions and compares everything that comes back with no tolerance. Reaching 6,275 of 6,275 identical observations took matching numpy's eight-accumulator summation tree, routing Python's power operator through the C library's pow behind a volatile, widening a float32 scale table the way numpy does, and running MuJoCo's forward pass a second time only under the same condition the Python code does, because the solver warm-starts. CI runs that comparison against a pinned commit of the Python repository, and rebuilds the C++ suite under AddressSanitizer and ThreadSanitizer, each of which needed a workaround for MuJoCo's prebuilt library. Measured afterwards on the same laptop: the full environment runs 20,287 env-steps/s in a 20-second burst at eight threads and settles between 13,300 and 16,200 over six minutes, with the same power-management curve the Python version shows; head to head under identical random actions the C++ threads deliver 1.9 to 2.0 times the Python processes at eight workers, above the 1.3× the README had set as the threshold for being worth the build. The same comparison showed the Python vector environment delivering about half the rate its project had budgeted from physics alone, because the inter-process round trip had never been in that composition. Thread efficiency at eight workers, 45%, matched the Python processes' 42%, so process isolation was not the scaling loss; the chip is. Then the proof that matters: the Python project's full 50M-step PPO run, repeated on this backend on three training seeds in about 3.1 hours each instead of 3.8 to 4.4, trains policies that score 339.4 ± 2.3 of 500 on the Python environment against 348.1 ± 8.1 for the ones trained there, with no backend difference in return or survival at three seeds, and it reproduces the same step-size failure and the same fix along the way.

Microduckのバランスタスクには、8つのforkプロセスで動くPython環境があります。本プロジェクトは同じ環境をC++17で8スレッド上に実装し、 pybind11 bindingと差し替え用クラスによって、Pythonの学習スクリプトを無修正で動かせるようにしたものです。時間計測より先に、両者をビット単位で一致させました。 テストではPythonにepisodeの乱数を引かせ、その値をC++側に渡したうえで、両方に同じ250個のactionを与え、返ってきたものをすべて許容誤差なしで比較します。 6,275個中6,275個のobservationを一致させるには、numpyの8アキュムレータによる加算ツリーを合わせ、Pythonのべき乗演算子をvolatile経由でCライブラリのpowに通し、 float32のスケールテーブルをnumpyと同じように拡張し、さらにソルバーがwarm-startするため、MuJoCoのforward passの2回目をPythonコードと同じ条件のときだけ実行する必要がありました。 CIはこの比較をPythonリポジトリの固定コミットに対して実行し、C++スイートをAddressSanitizerとThreadSanitizerで再ビルドします。どちらもMuJoCoのビルド済みライブラリに対する回避策が必要でした。 その後同じノートPCで計測したところ、環境全体は8スレッドの20秒burstで20,287 env-steps/s、6分間では13,300〜16,200に落ち着き、Python版と同じ電力管理の曲線を示しました。 同一のランダムactionでの直接比較では、8 workerでC++スレッドがPythonプロセスの1.9〜2.0倍で、READMEがビルドに見合う閾値として定めた1.3×を上回りました。 同じ比較から、Pythonのvector environmentの速度は、同プロジェクトが物理計算だけから見積もった値の約半分だと分かりました。プロセス間の往復がその積算に含まれていなかったためです。 8 workerでのスレッド効率45%はPythonプロセスの42%と同水準で、スケーリングの損失はプロセス分離ではなくチップによるものでした。 そして本当に重要な証明として、Pythonプロジェクトの50M stepのPPO学習をこのbackendで3つの学習seedについて再実行しました。所要時間は3.8〜4.4時間ではなく各約3.1時間で、 得られたpolicyはPython環境で500点満点中339.4 ± 2.3、Python環境で学習したものは348.1 ± 8.1でした。3 seedsではreturnにもsurvivalにもbackend間の差はなく、 途中で同じstep sizeの失敗と同じ対処も再現しています。