298 lines
10 KiB
Python
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)
|