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

298 lines
10 KiB
Python

"""Lightweight discovery of robot specs and lazy configuration loading.
Robot ids name the directories containing their calibration data. Only the
selected robot's fixed morphology template is imported to build a config.
"""
from __future__ import annotations
import importlib
import importlib.util
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any
from .robot_spec import MODEL_SUFFIX, RobotSpec, read_robot_spec
from .templates import TEMPLATE_MODULES
__all__ = [
"error_text",
"AssetSpec",
"TaskSpec",
"register",
"discover_robots",
"get",
"list_ids",
"all_specs",
"load_env_cfg",
"load_agent_cfg",
"load_cli_args",
"load_play_status",
"load_runner_cls",
"load_export_media",
]
#: Suffixes recognised as model files. A `--model` value carrying one of these, or
#: containing a path separator, is treated as a file path; anything else is treated
#: as a registered asset name.
_MODEL_SUFFIXES = frozenset({".xml", ".mjcf", ".mjb"})
def error_text(exc: Exception) -> str:
"""Get an exception's readable message.
`str()` on a `KeyError` re-reprs the message (adding a layer of quotes and
turning newlines into \\n), which reads badly when printed to a user. A failed
lookup raising KeyError is semantically right, so this is fixed on the display
side instead.
"""
if isinstance(exc, KeyError) and exc.args:
return str(exc.args[0])
return str(exc)
@dataclass(frozen=True)
class AssetSpec:
"""A model asset that can be fed to a task."""
name: str
"""The short name used on `--model`, e.g. ``robot_a``."""
path: Path
"""Absolute path to the MJCF / XML."""
description: str = ""
"""A one-line description, shown by `--list`."""
@dataclass(frozen=True)
class TaskSpec:
"""A task registration and its optional robot calibration."""
id: str
"""The fixed task name, used to select it on the command line. Must match the
directory under `tasks/`."""
assets: tuple[AssetSpec, ...] = ()
"""Named model choices. The first entry is the default."""
description: str = ""
"""A one-line description, shown by `--list`."""
tags: tuple[str, ...] = field(default_factory=tuple)
"""Free-form tags for filtering, e.g. ``("smoke",)`` / ``("locomotion", "quadruped")``."""
robot: RobotSpec | None = None
"""Physical calibration for a robot using a locked template."""
@property
def default_asset(self) -> AssetSpec | None:
return self.assets[0] if self.assets else None
def resolve_asset(self, requested: str | None) -> Path | None:
"""Resolve a `--model` value into an XML path.
Three forms:
None use the task's default asset
a registered name e.g. ``robot_a``
a file path e.g. ``assets/robot_a/robot.xml``
A replacement MJCF must retain the joints, home limits, and contact
names in the robot specification. The template checks those references
when building the environment.
"""
if requested is None:
return self.default_asset.path if self.default_asset else None
for asset in self.assets:
if asset.name == requested:
return asset.path
candidate = Path(requested).expanduser()
if "/" in requested or candidate.suffix.lower() in _MODEL_SUFFIXES:
if not candidate.is_file():
raise FileNotFoundError(f"model file does not exist: {candidate}")
resolved = candidate.resolve()
if self.robot is not None and resolved.suffix != MODEL_SUFFIX:
raise ValueError(f"locked templates require a model with the lowercase .xml suffix: {resolved}")
return resolved
known = ", ".join(a.name for a in self.assets) or "(this task registers no assets)"
raise KeyError(
f"task {self.id!r} has no asset named {requested!r}. "
f"Registered: {known}. A path to an .xml also works."
)
_REGISTRY: dict[str, TaskSpec] = {}
def register(
id: str, # noqa: A002 - matches gym.register's parameter name
assets: tuple[AssetSpec, ...] = (),
description: str = "",
tags: tuple[str, ...] = (),
robot: RobotSpec | None = None,
) -> TaskSpec:
"""Register a task. Registering the same id twice raises, so nothing is
silently overwritten.
``id`` must match the task's directory, or `load_env_cfg` will not find the
config.
"""
if id in _REGISTRY:
raise ValueError(
f"task id registered twice: {id!r} (an earlier import already defined it)"
)
names = [a.name for a in assets]
if len(names) != len(set(names)):
raise ValueError(f"task {id!r} has duplicate asset names: {names}")
spec = TaskSpec(id=id, assets=assets, description=description, tags=tags, robot=robot)
_REGISTRY[id] = spec
return spec
def discover_robots(root: Path) -> None:
"""Register every direct robot spec without importing it as Python code."""
for path in sorted(root.glob("*/robot_spec.py")):
robot = read_robot_spec(path)
template = TEMPLATE_MODULES[robot.family]
register(
id=robot.robot_id,
assets=(AssetSpec(robot.robot_id, robot.model_path, "Calibrated robot MJCF"),),
description=f"{template} locomotion",
tags=("locomotion", robot.family),
robot=robot,
)
def get(task_id: str) -> TaskSpec:
"""Look up a TaskSpec by id, listing every available id on failure rather than
raising a bare KeyError."""
try:
return _REGISTRY[task_id]
except KeyError:
available = "\n ".join(sorted(_REGISTRY)) or "(the registry is empty)"
raise KeyError(
f"unknown task {task_id!r}. Available tasks:\n {available}"
) from None
def list_ids(tag: str | None = None) -> list[str]:
"""List every task id, optionally filtered by tag."""
ids = sorted(_REGISTRY)
if tag is None:
return ids
return [i for i in ids if tag in _REGISTRY[i].tags]
def all_specs() -> list[TaskSpec]:
return [_REGISTRY[i] for i in sorted(_REGISTRY)]
# ── Load template configs and optional custom task hooks ───────────────────
def _module(task_id: str, name: str) -> Any:
"""Import `tasks.<task_id>.<name>`, turning "the directory does not follow the
convention" into a readable message."""
get(task_id) # confirm the id is registered first, for a better error
package = f"{__package__}.{task_id}"
dotted = f"{package}.{name}"
try:
return importlib.import_module(dotted)
except ModuleNotFoundError as e:
# What is missing may be the target module itself or any parent package
# along the path (a directory that was never created). Anything else is a
# dependency of the config module (mjlab, say) not being installed, and
# re-raising that unchanged is more useful.
if not (e.name == dotted or dotted.startswith(f"{e.name}.")):
raise
raise ModuleNotFoundError(
f"{dotted} not found. A task id must match a directory under tasks/, "
f"and that directory must contain {name}.py -- see tasks/registry.py."
) from None
def load_env_cfg(
task_id: str,
asset: Path | None = None,
play: bool = False,
task_args: dict[str, Any] | None = None,
) -> Any:
"""Build this task's environment config.
Args:
asset: model path from `--model`, resolved by `TaskSpec.resolve_asset`.
``None`` means the task's default asset.
play: build the replay configuration. For templates this disables training
disturbances and observation corruption and enables optional controls.
task_args: values for the arguments this task added to the parser itself,
keyed by their `dest`. See `load_cli_args`. Empty for every task that
adds none, which is why `env_cfg` signatures do not have to change.
"""
robot = get(task_id).robot
if robot is not None:
template = TEMPLATE_MODULES[robot.family]
module = importlib.import_module(f"{__package__}.templates.{template}.env_cfg")
return module.env_cfg(robot, asset=asset, play=play, **(task_args or {}))
return _module(task_id, "env_cfg").env_cfg(
asset=asset, play=play, **(task_args or {})
)
def load_agent_cfg(task_id: str) -> Any:
"""Get this task's own hyper-parameters (PPO, network, iteration count)."""
if get(task_id).robot is not None:
from .templates._locomotion import agent_cfg
return agent_cfg(task_id)
return _module(task_id, "rl_cfg").agent_cfg()
def load_runner_cls(task_id: str) -> type | None:
"""Get the runner class this task uses; None means the default OnPolicyRunner."""
if get(task_id).robot is not None:
from mjrl.tasks.runner import CurriculumRunner
return CurriculumRunner
return getattr(_module(task_id, "rl_cfg"), "runner_cls", lambda: None)()
def load_cli_args(task_id: str) -> Any:
"""Return a custom task's optional argument registration callable.
It accepts an argument group and returns the destination names that the
shared parser should forward to `load_env_cfg`. Locked templates use the
shared arguments only.
"""
if get(task_id).robot is not None:
return None
return getattr(
importlib.import_module(f"{__package__}.{task_id}"), "cli_args", None
)
def load_play_status(task_id: str) -> Any:
"""Return an optional `(entity, index, env) -> str` replay readout."""
if get(task_id).robot is not None:
from mjrl.tasks.play import velocity_status
return velocity_status
return getattr(_module(task_id, "rl_cfg"), "play_status", lambda: None)()
def load_export_media(task_id: str) -> Any | None:
"""Get this task's extra-artifact hook, or None if it has none.
Locked templates use the common policy artifacts. Custom registered tasks
may opt into extra artifacts through `export_media.py`.
"""
if get(task_id).robot is not None:
return None
dotted = f"{__package__}.{task_id}.export_media"
if importlib.util.find_spec(dotted) is None:
return None
return getattr(importlib.import_module(dotted), "export_media", None)