Files
chenlin c32df70326
Checks / Layout, translation and Colab checks (push) Has been cancelled
Checks / Ruff (push) Has been cancelled
Checks / Framework tests (native backend, CPU) (push) Has been cancelled
Checks / Portable Rust controller (push) Has been cancelled
release: v0.1 generic robot training and application platform
2026-11-05 11:05:01 +08:00

239 lines
10 KiB
Python

"""Backend and device resolution.
The emphasis is entirely on **not falling back**: explicitly asking for an
unavailable combination must fail rather than quietly become something else and
let someone believe they are training on a GPU. No test depends on whether this
machine has CUDA -- the detection functions are stubbed wherever a result is
needed.
"""
from __future__ import annotations
import sys
import pytest
from mjrl.backend.resolve import BackendUnavailable, resolve
# `from .resolve import resolve` in `rl/mjrl/backend/__init__.py` binds the
# **function** to the package attribute `mjrl.backend.resolve`, shadowing the
# submodule of the same name -- so `import mjrl.backend.resolve as m` yields the
# function, not the module. Stubbing the module's detection functions means going
# through sys.modules.
resolve_mod = sys.modules["mjrl.backend.resolve"]
@pytest.fixture(autouse=True)
def _clean_env(monkeypatch: pytest.MonkeyPatch) -> None:
"""External environment variables change the result, so they are cleared."""
monkeypatch.delenv("MJRL_BACKEND", raising=False)
monkeypatch.delenv("MJRL_DEVICE", raising=False)
def _stub_probes(monkeypatch: pytest.MonkeyPatch, *, gpu: bool) -> None:
for name in ("_mujoco_warp_importable", "_torch_cuda", "_warp_sees_cuda"):
monkeypatch.setattr(resolve_mod, name, lambda gpu=gpu: gpu)
# ── No fallback ───────────────────────────────────────────────────────────
def test_native_rejects_gpu_device() -> None:
with pytest.raises(BackendUnavailable, match="native backend only supports device=cpu"):
resolve(backend="native", device="cuda:0")
def test_warp_without_cuda_fails_instead_of_falling_back(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""The critical one: asking explicitly for a GPU the machine does not have
must fail, not silently switch to CPU."""
monkeypatch.setattr(resolve_mod, "_mujoco_warp_importable", lambda: True)
monkeypatch.setattr(resolve_mod, "_torch_cuda", lambda: False)
monkeypatch.setattr(resolve_mod, "_warp_sees_cuda", lambda: False)
with pytest.raises(BackendUnavailable, match="no usable\\s+CUDA device"):
resolve(backend="warp", device="cuda:0")
def test_warp_without_mujoco_warp_installed(monkeypatch: pytest.MonkeyPatch) -> None:
_stub_probes(monkeypatch, gpu=False)
with pytest.raises(BackendUnavailable, match="mujoco_warp is not installed"):
resolve(backend="warp", device="cuda:0")
def test_unknown_backend() -> None:
with pytest.raises(BackendUnavailable, match="unknown backend"):
resolve(backend="bogus")
# ── auto detection ────────────────────────────────────────────────────────
def test_auto_picks_native_without_gpu(monkeypatch: pytest.MonkeyPatch) -> None:
_stub_probes(monkeypatch, gpu=False)
r = resolve()
assert (r.backend, r.device) == ("native", "cpu")
assert r.forced is False
assert r.num_envs == 64
def test_auto_picks_warp_with_gpu(monkeypatch: pytest.MonkeyPatch) -> None:
_stub_probes(monkeypatch, gpu=True)
r = resolve()
assert (r.backend, r.device) == ("warp", "cuda:0")
assert r.num_envs == 4096
# ── Precedence: command line > environment ────────────────────────────────
def test_env_var_used_when_cli_is_auto(monkeypatch: pytest.MonkeyPatch) -> None:
_stub_probes(monkeypatch, gpu=True)
monkeypatch.setenv("MJRL_BACKEND", "native")
r = resolve()
assert r.backend == "native", "the environment wins even with a GPU present"
assert r.forced is True
def test_cli_beats_env_var(monkeypatch: pytest.MonkeyPatch) -> None:
_stub_probes(monkeypatch, gpu=False)
monkeypatch.setenv("MJRL_BACKEND", "warp")
r = resolve(backend="native", device="cpu")
assert r.backend == "native", "an explicit command-line value must beat the environment"
# ── Warnings ──────────────────────────────────────────────────────────────
def test_non_default_num_envs_warns_about_batch_size(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Changing num_envs changes PPO's effective batch, which has to be said or
nobody thinks to re-tune the hyper-parameters."""
_stub_probes(monkeypatch, gpu=False)
r = resolve(backend="native", device="cpu", num_envs=512)
assert any("num_envs=512" in n for n in r.notes)
def test_a_replay_count_is_not_a_batch_size(monkeypatch: pytest.MonkeyPatch) -> None:
"""A replay's `num_envs` is how many robots are on screen, so the batch-size
warning does not apply to it.
It used to print on every `play` -- "the hyper-parameters need re-tuning"
about a run that trains nothing -- and a warning that is always there is one
people learn to skip, including where it means something. The test above,
with the same count and `training` left at its default, is the control.
"""
_stub_probes(monkeypatch, gpu=False)
r = resolve(backend="native", device="cpu", num_envs=512, training=False)
assert r.num_envs == 512
assert not any("batch size" in n for n in r.notes), r.notes
def test_banner_reports_threads_for_native(monkeypatch: pytest.MonkeyPatch) -> None:
_stub_probes(monkeypatch, gpu=False)
banner = resolve(backend="native", device="cpu", cpu_threads=8).banner()
assert "backend=native" in banner
assert "threads=8" in banner
assert "(forced)" in banner
def test_the_automatic_thread_count_is_capped_below_the_core_count(
monkeypatch: pytest.MonkeyPatch,
) -> None:
""""Every core" is the obvious default and it is measurably wrong.
About half of a native step is serial (the gather and scatter between the
batch buffers and the per-environment MjData is Python-side), so by Amdahl
the parallel part is spent by around eight workers and every thread after
that is pure overhead. Measured on an i9-14900KF (32 logical cores), ms per
policy step at 64 environments: 8 threads 15.27, 16 threads 21.18, 24
(the physical core count) 22.39, 32 (every core) 22.36 -- the old default
was 46% off the optimum, and at 256 environments 16% off.
Nothing about that failure is visible: training runs, results are identical
(the thread count is not a hyper-parameter -- see
tests/test_native_determinism.py), it is simply slower than it should be on
exactly the machines bought for being fast.
The core count is faked rather than read: on a host with fewer cores than the
ceiling the assertion would hold no matter what the code did, and this test
has to fail on the machines the change is *for*. (Written the honest way
first, it passed against the old "every core" default on a 6-core laptop.)
"""
import importlib
# `import mjrl.backend.resolve as R` would bind the **function** `resolve`:
# the package's __init__ re-exports it, shadowing the submodule name.
R = importlib.import_module("mjrl.backend.resolve")
many = R.DEFAULT_MAX_THREADS * 4
monkeypatch.setattr(R, "_available_cores", lambda: many)
assert R._default_threads() == R.DEFAULT_MAX_THREADS, (
f"a {many}-core host must not default to every core"
)
r = resolve(backend="native", device="cpu", num_envs=1024, cpu_threads=0)
assert r.cpu_threads == R.DEFAULT_MAX_THREADS
# And the other direction: a small host uses what it has, never the ceiling.
few = 3
monkeypatch.setattr(R, "_available_cores", lambda: few)
assert R._default_threads() == few
def test_an_explicit_thread_count_beats_the_ceiling() -> None:
"""The ceiling is a default, not a limit.
It comes from measurements on two machines; someone on a third whose
workload scales further has to be able to say so, and `MJRL_CPU_THREADS`
is how.
"""
from mjrl.backend.resolve import DEFAULT_MAX_THREADS
asked = DEFAULT_MAX_THREADS * 4
r = resolve(backend="native", device="cpu", num_envs=1024, cpu_threads=asked)
assert r.cpu_threads == asked, "an explicit thread count must be honoured as given"
def test_backend_and_resolve_agree_on_the_default(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""One source for the number, or the two drift apart in silence.
`NativeSimulation` built directly -- in tests, or by anything not going
through `resolve` -- resolves its own thread count. Were that path to keep
its own copy of "every core", the measured default would apply to training
and not to the benchmarks written to check it.
"""
import importlib
from mjrl.backend.native_sim import _resolve_nthread
R = importlib.import_module("mjrl.backend.resolve") # see the note above
native = importlib.import_module("mjrl.backend.native_sim")
monkeypatch.setattr(native, "_DEFAULT_NTHREAD", None)
monkeypatch.setattr(R, "_available_cores", lambda: R.DEFAULT_MAX_THREADS * 4)
assert _resolve_nthread(None, 1024) == R._default_threads() == R.DEFAULT_MAX_THREADS
# And the environment-count cap still applies on that path
assert _resolve_nthread(None, 2) == 2
def test_threads_are_capped_by_env_count_so_the_banner_is_honest() -> None:
"""The printed thread count must be the one **actually used**.
`mujoco.rollout` requires the scratch list to be exactly nthread long and the
backend has only num_envs MjData copies, so the thread count is necessarily
capped by the environment count. Without capping in `resolve()`, the banner
would print "threads=32" while 16 actually ran.
This configuration's earlier defect was exactly "printing a value that never
took effect"; do not reintroduce it in a different form.
"""
r = resolve(backend="native", device="cpu", num_envs=4, cpu_threads=32)
assert r.cpu_threads == 4, f"threads not capped by environment count: {r.cpu_threads}"
assert "threads=4" in r.banner() if hasattr(r, "banner") else True
r = resolve(backend="native", device="cpu", num_envs=1024, cpu_threads=8)
assert r.cpu_threads == 8, "an explicit thread count must not be raised by the env count"