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

278 lines
12 KiB
Python

"""`play --app`: an app played in mjlab, and the ways that goes wrong quietly.
Two of them affect the route into every legacy application:
1. **The path.** `deploy.py --bundle` prints the build directory, which holds the
bundle and its `.app` side by side and is neither; handed that, `--app` has to
name the app inside rather than say only what is wrong. And the controller in
the app is loaded by its path, not by what `importlib` makes of its suffix:
on Windows a `controller.so` was a file with no spec, and every app fell
through to whatever `mjrl_fsm` was installed. On a Mac it is the key: the
platform string carries a version no bundle files its extension under.
2. **The keys.** MuJoCo's viewer reports a key's press alone, and
`mjrl.viewer.keys` adds its release. A press and a release handed on at one
instant are a toggle that never sees the key held, and two keys handed on in
another order than they came are a chord read the wrong way round.
"""
from __future__ import annotations
import math
import shutil
import sys
import zipfile
from pathlib import Path
import pytest
from mjrl.app_play import AppUnavailable, ViewerKeys, open_app
REPO = Path(__file__).resolve().parents[1]
CONTROLLER = """
[fsm]
initial_state = "walk"
[[fsm.state]]
name = "walk"
model = "walk.onnx"
task = "example_robot.tripod"
[[fsm.rule]]
when = "always"
enter = "@initial"
"""
def what_bundle_writes(tmp_path: Path) -> Path:
"""What `--bundle` writes: a bundle and its archive beside it, and no bundle itself."""
parent = tmp_path / "bundle_2026-01-01_00-00-00"
bundle = parent / "example_robot"
bundle.mkdir(parents=True)
(bundle / "bundle.json").write_text(
'{"modes": {"walk": {"contract": "walk.json"}}}\n', "utf-8")
(bundle / "walk.json").write_text('{"control": {"control_hz": 50.0}}\n', "utf-8")
(bundle / "controller.toml").write_text(CONTROLLER, "utf-8")
with zipfile.ZipFile(parent / "example_robot.app", "w") as app:
for f in bundle.iterdir():
app.write(f, f.name)
return parent
# ── 1. The path ───────────────────────────────────────────────────────────
def test_an_app_is_unzipped_and_its_default_task_read(tmp_path: Path) -> None:
"""The `.app` itself, the way people have it: unzipped for the run, and the
world's task read off the cascade's `always` rule -- through `@initial`
here, which a reading of `enter` alone would have taken for a state name."""
app = open_app(what_bundle_writes(tmp_path) / "example_robot.app")
try:
assert (app.root / "bundle.json").is_file()
assert app.default_task == "example_robot.tripod"
assert app.control_hz == 50.0
finally:
root = app.root
app.close()
assert not root.exists(), "the unzipped app outlived the run"
def test_the_bundle_directory_beside_it_plays_too(tmp_path: Path) -> None:
app = open_app(what_bundle_writes(tmp_path) / "example_robot")
assert app.default_task == "example_robot.tripod"
app.close()
assert (tmp_path / "bundle_2026-01-01_00-00-00/example_robot/bundle.json").is_file(), (
"closing an app that was not unzipped removed the bundle it was given"
)
def test_the_build_directory_names_the_app_in_it(tmp_path: Path) -> None:
parent = what_bundle_writes(tmp_path)
with pytest.raises(AppUnavailable) as raised:
open_app(parent)
assert str(parent / "example_robot.app") in str(raised.value)
def test_nothing_that_is_an_app_is_told_how_to_build_one(tmp_path: Path) -> None:
with pytest.raises(AppUnavailable) as raised:
open_app(tmp_path)
# The build command, not `--bundle`: that only picks where an app goes.
assert "python scripts/deploy.py --manifest" in str(raised.value)
not_zip = tmp_path / "x.app"
not_zip.write_text("not a zip", "utf-8")
with pytest.raises(AppUnavailable, match="zip"):
open_app(not_zip)
def test_the_app_s_controller_loads_whatever_its_suffix(tmp_path: Path, monkeypatch) -> None:
"""`importlib` picks an extension's loader by suffix, from this
interpreter's own list -- `.pyd` alone on Windows. A file with another got
no spec, and `play --app` fell through to the installed `mjrl_fsm`, saying
the app carried none: on Windows, every app, whose extension was named
`controller.so`.
Here the same failure the other way round: this platform's extension under
a suffix this interpreter does not use. The control shows `importlib` really
declines that suffix here, so the load is not passing for a reason Windows
would not share.
"""
import importlib.util
import sysconfig
from mjrl.app_play import _load_extension
deploy_spec = importlib.util.spec_from_file_location(
"deploy_for_legacy_play", REPO / "scripts/deploy.py"
)
deploy = importlib.util.module_from_spec(deploy_spec)
deploy_spec.loader.exec_module(deploy)
cargo = deploy.which("cargo")
if cargo is None:
pytest.skip("cargo is required to build the Python controller")
if sys.platform == "win32":
deploy.run(
[cargo, "build", "--release", "--no-default-features", "--features", "py", "--quiet"],
cwd=deploy.CRATE,
)
extension = deploy.CRATE / "target/release/mjrl_fsm.dll"
else:
extension = deploy.compile_extension(cargo, verbose=False)
platform = sysconfig.get_platform()
foreign = "controller.so" if sys.platform == "win32" else "controller.pyd"
renamed = tmp_path / "runtime/mjlab" / platform / foreign
renamed.parent.mkdir(parents=True)
shutil.copy2(extension, renamed)
assert importlib.util.spec_from_file_location("mjrl_fsm", renamed) is None, (
f"the control: {foreign} is a suffix importlib recognises here")
monkeypatch.delitem(sys.modules, "mjrl_fsm", raising=False)
manifest = {"runtimes": {"mjlab": {"commit": "test", "extensions": {
platform: {"file": renamed.relative_to(tmp_path).as_posix()}}}}}
module, origin = _load_extension(tmp_path, manifest)
assert origin.startswith(f"{foreign} from the app"), origin
assert hasattr(module, "Fsm")
def test_every_mac_finds_the_one_macos_controller() -> None:
"""A Mac's `sysconfig.get_platform()` carries the deployment target its
Python was built for, and a bundle files its macOS extension once, without
one -- so looked up by the exact string, no Mac finds it and `play --app`
says the app carries no controller for it. Every Python a Mac has reported
finds the universal one here.
The control: the lookup is not a prefix match that hands anything the Mac
file -- Linux and Windows get their own or nothing, a Mac gets nothing from
a bundle with no macOS build, and a Mac that built the bundle itself gets
its own exact build first.
"""
from mjrl.app_play import extension_for
built = {"linux-x86_64": {}, "win-amd64": {}, "macosx-universal2": {}}
for mac in ("macosx-14.0-arm64", "macosx-11.0-arm64", "macosx-10.9-universal2",
"macosx-10.13-x86_64"):
assert mac not in built
assert extension_for(built, mac) == "macosx-universal2", mac
assert extension_for(built, "linux-x86_64") == "linux-x86_64"
assert extension_for(built, "win-amd64") == "win-amd64"
assert extension_for(built, "linux-aarch64") is None
assert extension_for({"linux-x86_64": {}}, "macosx-14.0-arm64") is None
assert extension_for({**built, "macosx-14.0-arm64": {}}, "macosx-14.0-arm64") \
== "macosx-14.0-arm64"
def test_the_world_steps_at_the_app_s_fastest_mode() -> None:
"""The controller infers each mode when its period has passed and is
ticked once a world step, so a world slower than the app's fastest mode
runs that mode at the world's rate. The example_robot app's posture mode is 200
Hz; `example_robot.five_foot`'s world steps at 50, and ran it at 50 with nothing
said. `decimation` moves, the timestep does not -- and the 50 Hz app is the
control group, left at the task's own 4."""
from types import SimpleNamespace
from mjrl.app_play import step_the_world_at
def world() -> SimpleNamespace:
return SimpleNamespace(sim=SimpleNamespace(mujoco=SimpleNamespace(timestep=0.005)),
decimation=4)
for hz, decimation in ((200.0, 1), (50.0, 4), (100.0, 2)):
cfg = world()
step_the_world_at(cfg, hz)
assert (cfg.decimation, cfg.sim.mujoco.timestep) == (decimation, 0.005), hz
with pytest.raises(AppUnavailable, match="whole number"):
step_the_world_at(world(), 300.0)
def test_a_fall_is_the_controller_s_before_it_is_the_world_s(tmp_path: Path) -> None:
"""The world reset a robot tilted past 50 degrees in the same step the
controller would have called it tilted, past 50.02, so `tilted -> safe`
never fired in `play --app`. Moved past the controller's limit; a
termination already past it is the control group, and stays."""
from types import SimpleNamespace
from mjrl.app_play import FALL_MARGIN_RAD, leave_falls_to_the_app
app = open_app(what_bundle_writes(tmp_path) / "example_robot")
(app.root / "controller.toml").write_text(
CONTROLLER.replace('initial_state = "walk"', 'initial_state = "walk"\ntilt_limit = 0.873'),
"utf-8",
)
world = SimpleNamespace(terminations={
"fell_over": SimpleNamespace(params={"limit_angle": math.radians(50.0)}),
"upside_down": SimpleNamespace(params={"limit_angle": math.radians(170.0)}),
"time_out": SimpleNamespace(params={}),
})
assert leave_falls_to_the_app(world, app) == ["fell_over"]
assert world.terminations["fell_over"].params["limit_angle"] == pytest.approx(0.873 + FALL_MARGIN_RAD)
assert world.terminations["upside_down"].params["limit_angle"] == math.radians(170.0)
# ── 2. The keys ───────────────────────────────────────────────────────────
def test_a_key_is_down_from_its_press_to_its_release() -> None:
"""Held, a key goes down once and comes up once, however long it is held
and however many steps read it; a key the dictionary does not name is
nobody's. The release is the control group for the hold: the same reader
that kept it down lets it up."""
keys = ViewerKeys({71: "key_g"})
keys.report(71, True)
assert keys.changes() == (["key_g"], [])
for _ in range(100): # two seconds of steps
assert keys.changes() == ([], []), "a held key read as a second press or a release"
keys.report(71, False)
assert keys.changes() == ([], ["key_g"])
keys.report(999, True) # a key the dictionary does not name
assert keys.changes() == ([], [])
def test_a_tap_inside_one_step_is_down_for_that_step_and_up_at_the_next() -> None:
"""A press and its release between two steps. Handed over as both at one
instant, a `toggle` or a `rise` would never see the key held; so the press
is this step's and the release waits for the next. The control group is
the same two edges a step apart, which come out the same -- the deferral
only moves what would otherwise be lost."""
keys = ViewerKeys({265: "key_up"})
keys.report(265, True)
keys.report(265, False)
assert keys.changes() == (["key_up"], [])
assert keys.changes() == ([], ["key_up"])
assert keys.changes() == ([], [])
keys.report(265, True)
assert keys.changes() == (["key_up"], [])
keys.report(265, False)
assert keys.changes() == ([], ["key_up"])
def test_two_keys_down_in_one_step_go_down_in_the_order_they_did() -> None:
"""A chord is its modifier held and then its direction: `with` reads the
modifier as down when the direction rises. Two keys pressed inside one
step are handed on in the order they came, not by name -- by name,
`key_left_ctrl` would always come first, and right-then-Ctrl would read as
the chord."""
keys = ViewerKeys({262: "key_right", 341: "key_left_ctrl"})
keys.report(262, True)
keys.report(341, True)
assert keys.changes() == (["key_right", "key_left_ctrl"], [])