697 lines
30 KiB
Python
697 lines
30 KiB
Python
"""The command-line skeleton shared by the entry points under scripts/.
|
|
|
|
train / play / export differ only in what they do *after* obtaining a TaskSpec, a
|
|
Resolution and a model path. Argument parsing, registry lookup, asset resolution
|
|
and backend resolution are identical, so they live here.
|
|
|
|
**Nothing here rewrites sys.path.** `mjrl`, `tasks`, `mjlab` and `rsl_rl` all come
|
|
from `pip install -e .` (see the two package roots in pyproject.toml), so imports
|
|
depend on the environment rather than on happening to run from the repository
|
|
root. Inserting the repository root at the top of every script would make "where
|
|
you ran it from" an implicit dependency, and that is exactly the source of the
|
|
shadowing trap documented in docs/VENDOR.md.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import argparse
|
|
import contextlib
|
|
import sys
|
|
from collections.abc import Sequence
|
|
from pathlib import Path
|
|
|
|
from mjrl.dotenv import env_default as _env
|
|
from mjrl.dotenv import env_choice, env_flag, load_dotenv
|
|
from tasks.paths import REPO_ROOT
|
|
|
|
# Load .env into os.environ *before* parsing (without overwriting existing values);
|
|
# the defaults below then read from os.environ. Precedence follows for free:
|
|
# command line > shell environment > .env.local > .env > built-in default
|
|
load_dotenv(REPO_ROOT / ".env", REPO_ROOT / ".env.local")
|
|
|
|
|
|
def _int_env(name: str, fallback: int | None = None) -> int | None:
|
|
"""Read an integer environment variable, erroring rather than silently
|
|
falling back to the default when the value is not an integer."""
|
|
raw = _env(name)
|
|
if raw is None:
|
|
return fallback
|
|
try:
|
|
return int(raw)
|
|
except ValueError:
|
|
raise SystemExit(f"error: {name}={raw!r} is not an integer (check .env)") from None
|
|
|
|
|
|
def _positive_int(raw: str) -> int:
|
|
try:
|
|
value = int(raw)
|
|
except ValueError:
|
|
raise argparse.ArgumentTypeError("expected a positive integer") from None
|
|
if value <= 0:
|
|
raise argparse.ArgumentTypeError("expected a positive integer")
|
|
return value
|
|
|
|
|
|
def _bool_env(name: str, fallback: bool) -> bool:
|
|
"""Read a switch from the environment, erroring rather than silently falling
|
|
back when the value is not one -- the same rule as `_int_env`, and for the same
|
|
reason: a setting that is ignored looks like a feature that does not work."""
|
|
try:
|
|
return env_flag(name, fallback)
|
|
except ValueError as e:
|
|
raise SystemExit(f"error: {e} (check .env)") from None
|
|
|
|
|
|
def _choice_env(name: str, choices: Sequence[str], fallback: str) -> str:
|
|
"""Read one of `choices` from the environment, erroring rather than passing an
|
|
unrecognised value on.
|
|
|
|
**argparse checks `choices` only for values typed on the command line**, never
|
|
for a default -- so `default=_env(...)` with `choices=[...]` validates nothing,
|
|
and the bad value goes wherever the resolved argument goes.
|
|
"""
|
|
try:
|
|
chosen = env_choice(name, choices, fallback)
|
|
except ValueError as e:
|
|
raise SystemExit(f"error: {e} (check .env)") from None
|
|
# `fallback` is a str, so `chosen` never is None; coalesce rather than assert,
|
|
# which `python -O` would strip.
|
|
return chosen if chosen is not None else fallback
|
|
|
|
|
|
#: `--strip-visual`'s three states and what each means to `mjrl.backend.resolve`.
|
|
#: **One definition**, so what argparse accepts and what the backend is handed
|
|
#: cannot drift apart: they used to be two separate literals, and a value in only
|
|
#: one of them was a `KeyError` from inside `resolve_all`.
|
|
STRIP_VISUAL: dict[str, bool | None] = {"auto": None, "on": True, "off": False}
|
|
|
|
#: `--backend`'s three values. `auto` detects; the other two never fall back.
|
|
BACKENDS = ("auto", "warp", "native")
|
|
|
|
|
|
def build_parser(
|
|
prog: str, description: str, *, replay: bool = False
|
|
) -> argparse.ArgumentParser:
|
|
p = argparse.ArgumentParser(prog=prog, description=description)
|
|
p.add_argument(
|
|
"--task",
|
|
default=_env("MJRL_TASK"),
|
|
help="task id; see --list. Falls back to MJRL_TASK in .env",
|
|
)
|
|
p.add_argument(
|
|
"--model",
|
|
default=_env("MJRL_MODEL"),
|
|
metavar="NAME|PATH",
|
|
help="which model asset to use: an asset name registered by the task, or a "
|
|
"path to an .xml file (MuJoCo picks its decoder by extension and has none "
|
|
"for .mjcf). Falls back to MJRL_MODEL in .env, then to the task's "
|
|
"default asset",
|
|
)
|
|
p.add_argument(
|
|
"--list",
|
|
action="store_true",
|
|
help="list every registered task with its available assets, then exit",
|
|
)
|
|
|
|
g = p.add_argument_group("backend and device (defaults come from .env)")
|
|
g.add_argument(
|
|
"--backend", default=_choice_env("MJRL_BACKEND", BACKENDS, "auto"),
|
|
choices=BACKENDS,
|
|
)
|
|
g.add_argument(
|
|
"--device", default=_env("MJRL_DEVICE", "auto"),
|
|
help="auto | cuda:0 | cpu. With --backend auto on a machine with CUDA, cpu "
|
|
"still gets warp, whose cpu device is a serial debugging path; pair it "
|
|
"with --backend native for the CPU backend",
|
|
)
|
|
# `--num_envs` is two quantities under one flag, and each has its own `.env`
|
|
# key. Training's is PPO's batch size: every hyper-parameter is tuned against
|
|
# it. A replay's is how many robots are on screen, all running one policy.
|
|
# They shared MJRL_NUM_ENVS once, and the repository's 4096 -- right for
|
|
# training on warp -- built 4096 native CPU environments to replay an app's
|
|
# controller that reads one, and never got past building them.
|
|
if replay:
|
|
g.add_argument(
|
|
"--num_envs", "--num-envs", type=int, default=_int_env("MJRL_PLAY_NUM_ENVS", 1),
|
|
help="how many environments to replay, every one running the same "
|
|
"policy. Falls back to MJRL_PLAY_NUM_ENVS in .env, then to 1. "
|
|
"MJRL_NUM_ENVS is training's batch size and is not read",
|
|
)
|
|
else:
|
|
g.add_argument(
|
|
"--num_envs", "--num-envs", type=int, default=_int_env("MJRL_NUM_ENVS"),
|
|
help="parallel environments, which is PPO's batch size: changing it "
|
|
"means re-tuning. Falls back to MJRL_NUM_ENVS in .env, then to the "
|
|
"backend's default (warp 4096 / native 64)",
|
|
)
|
|
g.add_argument(
|
|
"--cpu_threads", type=int, default=_int_env("MJRL_CPU_THREADS", 0),
|
|
help="0 means the available cores, at most 8, then capped by num_envs; "
|
|
"past about 8 the step is serial-bound (DEFAULT_MAX_THREADS in "
|
|
"mjrl/backend/resolve.py)",
|
|
)
|
|
g.add_argument(
|
|
"--strip-visual", dest="strip_visual",
|
|
default=_choice_env("MJRL_STRIP_VISUAL", tuple(STRIP_VISUAL), "auto"),
|
|
choices=tuple(STRIP_VISUAL),
|
|
help=(
|
|
"native: strip visual-only meshes. Domain randomisation copies one "
|
|
"MjModel per environment, including visual meshes not used by physics. "
|
|
"auto = strip once the per-environment models exceed 2 GiB. "
|
|
"Cost: camera sensors then see collision geometry rather than "
|
|
"appearance meshes (the live viewer is unaffected)"
|
|
),
|
|
)
|
|
g.add_argument(
|
|
"--warp-max-constraints", type=_positive_int, metavar="N",
|
|
help="Warp constraint capacity per world (njmax). Defaults to the run's saved "
|
|
"setting, the task or scene setting, or Warp's heuristic",
|
|
)
|
|
g.add_argument(
|
|
"--warp-max-contacts", type=_positive_int, metavar="N",
|
|
help="Warp contact allocation per world (nconmax). Warp pools contact "
|
|
"capacity across all worlds",
|
|
)
|
|
g.add_argument(
|
|
"--dry-run",
|
|
action="store_true",
|
|
help="resolve task, asset and backend, print the result, and build nothing",
|
|
)
|
|
return p
|
|
|
|
|
|
def print_task_table() -> None:
|
|
"""List every task. Assets are listed too, since that is where `--model`'s
|
|
valid values come from."""
|
|
import tasks
|
|
|
|
specs = tasks.all_specs()
|
|
if not specs:
|
|
print("The registry is empty.")
|
|
return
|
|
width = max(len(s.id) for s in specs)
|
|
print(f"{'task id':<{width}} description")
|
|
print(f"{'-' * width} {'-' * 52}")
|
|
for spec in specs:
|
|
print(f"{spec.id:<{width}} {spec.description}")
|
|
for i, asset in enumerate(spec.assets):
|
|
mark = "default" if i == 0 else " "
|
|
print(f"{'':<{width}} --model {asset.name} [{mark}] {asset.description}")
|
|
print("\n--model also accepts a path to an .xml file.")
|
|
|
|
import scenes
|
|
|
|
specs = scenes.all_specs()
|
|
if specs:
|
|
width = max(len(s.id) for s in specs)
|
|
print(f"\n{'scene':<{width}} description (--scene)")
|
|
print(f"{'-' * width} {'-' * 52}")
|
|
for spec in specs:
|
|
print(f"{spec.id:<{width}} {spec.description}")
|
|
print("\nWithout --scene the task's own configuration is left untouched.")
|
|
|
|
|
|
def parse_with_task_args(parser: argparse.ArgumentParser, task: str | None = None):
|
|
"""Parse, after letting the selected task add arguments of its own.
|
|
|
|
Returns the namespace, with the task's own values collected on it as
|
|
`args.task_args` -- a dict keyed by `dest`, ready to hand straight to
|
|
`tasks.load_env_cfg`. On the namespace rather than beside it so that nothing
|
|
between here and there has to carry a second value it does not use; every
|
|
entry point already passes `args` down whole.
|
|
|
|
**Two phases, because the task id is itself an argument.** A throwaway parser
|
|
finds `--task` (falling back to `MJRL_TASK` exactly as the real one does), the
|
|
task adds whatever it takes, and then the real parse runs. The first parser has
|
|
`add_help=False` on purpose: with help enabled, `--help` would be handled in
|
|
phase one and print a usage message missing the very arguments this exists to
|
|
add.
|
|
|
|
An unknown task is not an error here -- it is `resolve_all`'s, which says so
|
|
properly and lists the alternatives. This just declines to ask it anything.
|
|
|
|
`task` replaces `MJRL_TASK` as the default, for both phases: an entry point
|
|
that knows the task before the command line names one (`play --app`, whose
|
|
app does) and would otherwise add the options of the wrong task's.
|
|
"""
|
|
import tasks
|
|
|
|
if task is not None:
|
|
parser.set_defaults(task=task)
|
|
pre = argparse.ArgumentParser(add_help=False)
|
|
pre.add_argument("--task", default=task or _env("MJRL_TASK"))
|
|
task = pre.parse_known_args()[0].task
|
|
names: tuple[str, ...] = ()
|
|
if task:
|
|
try:
|
|
add = tasks.load_cli_args(task)
|
|
except KeyError:
|
|
add = None
|
|
if add is not None:
|
|
names = tuple(add(parser.add_argument_group(f"{task} options")))
|
|
# The same two phases again for the **scene**, which can also take options of
|
|
# its own (`scenes/rough.py` picks a terrain row and column). Separate from
|
|
# the task's: a run names a task and a scene independently, and collapsing
|
|
# them into one dict would mean a scene and a task could not both use the
|
|
# name `--row`.
|
|
#
|
|
# Guarded on the entry point having `--scene` at all. `export.py` does not --
|
|
# nothing a scene changes reaches an ONNX file -- and offering its options
|
|
# there would be the "accepted and then ignored" flag `add_scene_args`
|
|
# refuses to be.
|
|
scene_names: tuple[str, ...] = ()
|
|
if any(a.dest == "scene" for a in parser._actions): # noqa: SLF001
|
|
import scenes
|
|
|
|
pre_scene = argparse.ArgumentParser(add_help=False)
|
|
pre_scene.add_argument("--scene", default=_env("MJRL_SCENE"))
|
|
scene_id = pre_scene.parse_known_args()[0].scene
|
|
if scene_id:
|
|
try:
|
|
add_scene = scenes.load_cli_args(scene_id)
|
|
except (KeyError, ModuleNotFoundError):
|
|
add_scene = None
|
|
if add_scene is not None:
|
|
scene_names = tuple(
|
|
add_scene(parser.add_argument_group(f"{scene_id} scene options"))
|
|
)
|
|
|
|
args = parser.parse_args()
|
|
args.task_args = {name: getattr(args, name) for name in names}
|
|
args.scene_args = {name: getattr(args, name) for name in scene_names}
|
|
return args
|
|
|
|
|
|
def resolve_all(args: argparse.Namespace, *, for_training: bool = False):
|
|
"""Return (TaskSpec, Resolution, asset).
|
|
|
|
Any failure exits with an actionable message. `asset` is the resolved model
|
|
path, or None when the task registers no assets. `for_training` is the entry
|
|
point saying which it is, so that an argument only one of them accepts is
|
|
refused here -- where `--dry-run` can still see it.
|
|
"""
|
|
import tasks
|
|
from mjrl.backend import BackendUnavailable, resolve
|
|
from tasks.registry import error_text
|
|
|
|
if not args.task:
|
|
print(
|
|
"error: no task. Pass --task, or set MJRL_TASK in the repository's .env.\n"
|
|
"Use --list to see the available tasks.",
|
|
file=sys.stderr,
|
|
)
|
|
raise SystemExit(2)
|
|
|
|
try:
|
|
spec = tasks.get(args.task)
|
|
except KeyError as e:
|
|
print(f"error: {error_text(e)}", file=sys.stderr)
|
|
raise SystemExit(2) from None
|
|
|
|
try:
|
|
asset: Path | None = spec.resolve_asset(args.model)
|
|
except (KeyError, FileNotFoundError, ValueError) as e:
|
|
print(f"error: {error_text(e)}", file=sys.stderr)
|
|
raise SystemExit(2) from None
|
|
|
|
try:
|
|
res = resolve(
|
|
backend=args.backend,
|
|
device=args.device,
|
|
num_envs=args.num_envs,
|
|
cpu_threads=args.cpu_threads,
|
|
strip_visual=STRIP_VISUAL[getattr(args, "strip_visual", "auto")],
|
|
training=for_training,
|
|
)
|
|
except BackendUnavailable as e:
|
|
print(f"error: {e}", file=sys.stderr)
|
|
raise SystemExit(1) from None
|
|
|
|
if res.backend != "warp" and any(
|
|
getattr(args, name, None) is not None
|
|
for name in ("warp_max_constraints", "warp_max_contacts")
|
|
):
|
|
raise SystemExit("[mjrl] --warp-max-constraints and --warp-max-contacts require Warp")
|
|
|
|
# Validate --scene here, though it is applied much later, so that --dry-run
|
|
# catches a typo. Checking arguments is the whole purpose of --dry-run, and a
|
|
# misspelled scene that only surfaces after the environment is built would
|
|
# get past exactly the check meant to find it. Same reason --model is
|
|
# resolved here rather than at use.
|
|
if getattr(args, "scene", None):
|
|
import scenes
|
|
from scenes.package import PackageError, is_package_path, read_package
|
|
|
|
try:
|
|
if is_package_path(args.scene):
|
|
# Read it now rather than at use, for the same reason as the
|
|
# registry lookup: --dry-run exists to catch a bad argument, and
|
|
# a package whose hashes do not match is one. So is a package
|
|
# handed to training -- and that refusal has to be here rather
|
|
# than where scenes are applied, because --dry-run stops first.
|
|
refuse_package_for_training(read_package(args.scene), for_training)
|
|
else:
|
|
scenes.get(args.scene)
|
|
except KeyError as e:
|
|
print(f"error: {error_text(e)}", file=sys.stderr)
|
|
raise SystemExit(2) from None
|
|
except PackageError as e:
|
|
print(f"error: {e}", file=sys.stderr)
|
|
raise SystemExit(2) from None
|
|
|
|
print(res.banner())
|
|
if asset is not None:
|
|
print(f"[mjrl] task={spec.id} model={asset}")
|
|
return spec, res, asset
|
|
|
|
|
|
def add_scene_args(parser: argparse.ArgumentParser) -> None:
|
|
"""Add `--scene`. Only the entry points that put a picture on screen take it.
|
|
|
|
Not in the shared parser, for the same reason `--headless` is not: export
|
|
produces an ONNX file and a contract, and nothing a scene changes can reach
|
|
either. A flag that is accepted and then ignored is worse than a missing one
|
|
-- it reads as supported.
|
|
"""
|
|
parser.add_argument(
|
|
"--scene",
|
|
default=_env("MJRL_SCENE"),
|
|
metavar="NAME",
|
|
help="how the world looks: ground, sky and lights; see --list. Also takes a "
|
|
"path to an imported kk-scene-package/1 (a directory or .zip), which "
|
|
"scripts/play.py accepts and scripts/train.py refuses. Falls back "
|
|
"to MJRL_SCENE in .env, and to the task's own configuration when neither "
|
|
"is given",
|
|
)
|
|
|
|
|
|
def apply_scene(env_cfg, args, *, for_training: bool = False) -> None:
|
|
"""Apply `--scene` to a freshly built environment config.
|
|
|
|
After the task rather than before: the task configures the ground it was
|
|
designed for, and a scene is the user overruling that look for this run.
|
|
Passing no scene leaves the config alone, so the default behaviour is
|
|
unchanged rather than merely equivalent.
|
|
|
|
`for_training` is the caller saying which entry point it is, because an
|
|
imported scene package is refused by one of them -- see
|
|
`refuse_package_for_training`.
|
|
"""
|
|
scene_id = getattr(args, "scene", None)
|
|
if not scene_id:
|
|
return
|
|
|
|
import scenes
|
|
from scenes.package import PackageError, is_package_path
|
|
from tasks.registry import error_text
|
|
|
|
if is_package_path(scene_id):
|
|
try:
|
|
_apply_package(env_cfg, scene_id, for_training=for_training)
|
|
except PackageError as e:
|
|
print(f"error: {e}", file=sys.stderr)
|
|
raise SystemExit(2) from None
|
|
return
|
|
|
|
try:
|
|
scene = scenes.apply(env_cfg, scene_id, **getattr(args, "scene_args", {}))
|
|
except (KeyError, ModuleNotFoundError) as e:
|
|
print(f"error: {error_text(e)}", file=sys.stderr)
|
|
raise SystemExit(2) from None
|
|
# Say what it changed, in the order that matters. "look only" beside a
|
|
# warning that the scene just added a ball is worse than saying nothing:
|
|
# the banner is the line people skim, and it was contradicting the warning
|
|
# directly above it.
|
|
changed = []
|
|
if scene.props:
|
|
changed.append(f"{len(scene.props)} physical prop(s)")
|
|
if scene.terrain_type:
|
|
changed.append("the ground")
|
|
changed.append("the look")
|
|
print(f"[mjrl] scene={scene_id} (changes {', '.join(changed)})")
|
|
|
|
|
|
SCHEMA_LABEL = "kk-scene-package/1"
|
|
|
|
|
|
def refuse_package_for_training(package, for_training: bool) -> None:
|
|
"""Refuse an imported package on the training entry point.
|
|
|
|
The refusal is the feature. The package is one room at the world origin and
|
|
mjlab replicates nothing that is not an entity, so at any real `--num_envs`
|
|
exactly one robot is indoors and every other one trains on empty ground.
|
|
Training runs, converges to something, and nothing anywhere reports a
|
|
problem -- the same failure class as rough terrain with no height scan.
|
|
Refusing beats warning, because a warning here would be about a run that is
|
|
already meaningless.
|
|
"""
|
|
if not for_training:
|
|
return
|
|
print(
|
|
f"error: scene package {package.id!r} cannot be used for training. It is one "
|
|
f"room at the world origin, and mjlab places environments on a grid -- only the "
|
|
f"robot at the origin would be inside it, while every other environment trained "
|
|
f"on empty ground. Nothing would report that. Use it with scripts/play.py.",
|
|
file=sys.stderr,
|
|
)
|
|
raise SystemExit(2)
|
|
|
|
|
|
def _apply_package(env_cfg, source: str, *, for_training: bool) -> None:
|
|
"""Apply an imported `kk-scene-package/1`.
|
|
|
|
Routed through `scenes.registry.apply_scene`, the same function a registered
|
|
scene goes through, so an imported one cannot quietly skip a check: the prop
|
|
name clash, the per-environment placement, the contact budget and the warning
|
|
that physical props change the run are all in there.
|
|
|
|
Unlike a registered scene, this one's geometry **collides**: a room the robot
|
|
walks through is not a room. `Scene.decorate` may normally only add geometry
|
|
the robot cannot touch, because a look should not change the task -- and the
|
|
refusal above, rather than a weaker room, is what keeps that protection where
|
|
it matters.
|
|
"""
|
|
import scenes
|
|
from scenes.package import load_package, read_package
|
|
|
|
package = read_package(source)
|
|
refuse_package_for_training(package, for_training)
|
|
scene = scenes.apply_scene(env_cfg, load_package(source), package.id)
|
|
|
|
counts = package.manifest.get("world", {}).get("counts", {})
|
|
print(
|
|
f"[mjrl] scene={package.id} (imported {SCHEMA_LABEL}: {counts.get('geoms', '?')} geoms, "
|
|
f"{len(scene.props)} entities, {counts.get('lights', '?')} lights; "
|
|
f"nconmax={scene.nconmax} njmax={scene.njmax} measured by settling the world)"
|
|
)
|
|
# Said out loud because it is the one way this differs from every registered
|
|
# scene: those may only add geometry the robot cannot touch.
|
|
print(
|
|
"[mjrl] the imported world collides -- walls and furniture are solid, so contacts "
|
|
"and solver load are not comparable to a run on a bare scene"
|
|
)
|
|
# A package's own `rules` asks a backend that cannot do flex to say so rather
|
|
# than drop it silently. This backend does not drop it, which is worse: it
|
|
# runs, and it runs at a speed that reads as a slow machine. Measured here,
|
|
# 4 environments on an RTX 5090: a package with one 195-vertex cloth ran at
|
|
# 0.4 fps / 0.01x real time against 6.7 fps / 0.13x for one without.
|
|
flex = package.manifest.get("flex") or []
|
|
if flex:
|
|
print(
|
|
f"[mjrl] warning: this package carries {len(flex)} flex (soft body). It "
|
|
f"simulates, but roughly an order of magnitude slower -- 0.01x real time "
|
|
f"against 0.13x for a package without one, measured at 4 environments. "
|
|
f"Nothing else reports this; it reads as a slow machine."
|
|
)
|
|
|
|
# ── Checkpoints, shared by train.py and play.py ───────────────────────────
|
|
|
|
|
|
def resolve_checkpoint(wanted, task_id: str, asset: Path | None) -> Path:
|
|
"""Turn a `--checkpoint` value into a checkpoint that exists.
|
|
|
|
`wanted` is None for "the newest one under `logs/<model>/<task>/`", which is
|
|
what both callers mean by the default: for play, the run that just finished;
|
|
for `train --resume`, the training to be continued.
|
|
|
|
The search itself is `mjrl.checkpoint`; what this adds is the one thing that
|
|
module deliberately does not know -- that the tree to search is the same
|
|
`logs/<model>/<task>` train writes into -- plus turning the failure into an
|
|
exit, since every caller is a command-line entry point.
|
|
"""
|
|
from mjrl.checkpoint import find_checkpoint
|
|
from tasks.paths import log_root_for
|
|
|
|
try:
|
|
return find_checkpoint(wanted, Path(log_root_for(asset)) / task_id)
|
|
except FileNotFoundError as e:
|
|
print(f"error: {e}", file=sys.stderr)
|
|
raise SystemExit(2) from None
|
|
|
|
|
|
# ── The live viewer, shared by train.py and play.py ───────────────────────
|
|
|
|
|
|
def add_viewer_args(
|
|
parser: argparse.ArgumentParser, ui_default: bool = False, fps_default: float = 30.0
|
|
) -> None:
|
|
"""Add the live-viewer switches. Both train and play take the same ones.
|
|
|
|
Args:
|
|
ui_default: whether MuJoCo's own panels start shown. One of **the two
|
|
switches whose default differs between the two entry points**: `play`
|
|
exists to look at a policy, so the controls are wanted; `train` keeps
|
|
a window open for hours and nobody reaches for them.
|
|
fps_default: frames a second, the other one. `play` is watched closely
|
|
and asks for 60; `train` is glanced at, and 30 halves the copies taken
|
|
on its simulation thread. Either way the drawing itself is on the
|
|
viewer's own thread (see `mjrl/viewer/live.py`), so a higher rate no
|
|
longer slows the world down the way it did.
|
|
"""
|
|
g = parser.add_argument_group("live viewer")
|
|
g.add_argument(
|
|
"--headless",
|
|
action="store_true",
|
|
help="do not open the live viewer. **It is on by default**, drawing at most "
|
|
"128 environments (all of them below 128; above that it prints how many it "
|
|
"drew). With no usable display this happens automatically",
|
|
)
|
|
g.add_argument(
|
|
"--viewer-env", type=int, default=None,
|
|
help="which environment the camera follows. Defaults to the one nearest the "
|
|
"**centre of the scene** -- environment 0 sits at a corner of the grid, so "
|
|
"following it leaves two sides empty",
|
|
)
|
|
g.add_argument(
|
|
"--viewer-fps", type=float, default=fps_default,
|
|
help=f"frames a second the window shows; {fps_default:g} by default here. "
|
|
f"Drawing runs on a thread of its own, so this costs the simulation one "
|
|
f"copy of the state per frame and nothing else",
|
|
)
|
|
g.add_argument(
|
|
"--viewer-env-num", type=int, default=None,
|
|
help="how many environments to draw (including the followed one); 128 if not "
|
|
"given. **Not the same as --viewer-env**: that one is which, this one is "
|
|
"how many",
|
|
)
|
|
# `BooleanOptionalAction` rather than `store_true`, because the default
|
|
# differs by entry point: a flag that is on by default needs a way to be
|
|
# turned off, and `--no-viewer-ui` is that way.
|
|
g.add_argument(
|
|
"--viewer-ui", action=argparse.BooleanOptionalAction, default=ui_default,
|
|
help=f"show MuJoCo's own panels -- rendering flags, visualisation "
|
|
f"options, the model tree. **{'On' if ui_default else 'Off'} by default "
|
|
f"here.** Watching a policy is when those controls get used; a training "
|
|
f"run is hours long and nobody touches them, so they only cost frame "
|
|
f"time. Note they edit the *followed* environment only; the rest of the "
|
|
f"drawn field is not theirs to change",
|
|
)
|
|
|
|
|
|
@contextlib.contextmanager
|
|
def maybe_viewer(env, args):
|
|
"""Attach the live viewer, unless `--headless` or there is no usable display.
|
|
|
|
**It is on by default.** With no display it falls back to headless rather than
|
|
crashing: otherwise running over ssh, or from cron, would fail outright because
|
|
the viewer defaults to on, which is far worse than not seeing the picture.
|
|
"""
|
|
if args.headless:
|
|
yield None
|
|
return
|
|
from mjrl.viewer.live import no_display_reason
|
|
|
|
reason = no_display_reason()
|
|
if reason:
|
|
print(f"[mjrl] going headless: {reason}. Use --headless to say so explicitly")
|
|
yield None
|
|
return
|
|
|
|
from mjrl.viewer.live import LiveViewer
|
|
|
|
try:
|
|
viewer = LiveViewer(
|
|
env.sim,
|
|
env_index=args.viewer_env,
|
|
fps=args.viewer_fps,
|
|
# Draw the environments nearest the camera. Without origins it would
|
|
# take the first few by index, and 4096 environments form a 64x64 grid
|
|
# -- the first 128 are exactly the two outermost rows.
|
|
env_origins=getattr(env.scene, "env_origins", None),
|
|
max_draw_envs=args.viewer_env_num,
|
|
show_ui=getattr(args, "viewer_ui", False),
|
|
).start()
|
|
except Exception as e: # noqa: BLE001
|
|
# A viewer that fails to open must never take the run down with it -- the
|
|
# window is there to look at, it is not part of the run.
|
|
print(f"[mjrl] live viewer failed to open, continuing headless: "
|
|
f"{type(e).__name__}: {e}")
|
|
yield None
|
|
return
|
|
try:
|
|
yield viewer
|
|
finally:
|
|
viewer.stop()
|
|
|
|
|
|
# ── TensorBoard, started alongside training ───────────────────────────────
|
|
|
|
|
|
def add_tensorboard_args(parser: argparse.ArgumentParser) -> None:
|
|
"""Add the TensorBoard switches. Only train.py has anything to serve."""
|
|
g = parser.add_argument_group("tensorboard")
|
|
# A pair rather than a lone `--no-tensorboard`: the precedence the whole
|
|
# configuration rests on is "command line > .env", and with only the negative
|
|
# form there is no way back **on** for one run once `.env` has turned it off.
|
|
g.add_argument(
|
|
"--tensorboard",
|
|
action=argparse.BooleanOptionalAction,
|
|
default=_bool_env("MJRL_TENSORBOARD", True),
|
|
help="start TensorBoard on this run's log directory, on the first free "
|
|
"port at or after --tb-port. **It is on by default**: --no-tensorboard "
|
|
"turns it off for one run, MJRL_TENSORBOARD=off in .env turns it off for "
|
|
"good, and --tensorboard turns it back on over that",
|
|
)
|
|
g.add_argument(
|
|
"--tb-port", type=int, default=_int_env("MJRL_TB_PORT", 6006),
|
|
help="preferred port. Taken ports are skipped, so a second run gets the "
|
|
"next one rather than failing",
|
|
)
|
|
g.add_argument(
|
|
"--tb-scope", choices=["run", "task", "all"], default="task",
|
|
help="how much to serve: this run only, every run of this task and model "
|
|
"(the default, so the previous run is there to compare against), or the "
|
|
"whole logs/ tree",
|
|
)
|
|
|
|
|
|
@contextlib.contextmanager
|
|
def maybe_tensorboard(log_dir: Path, args):
|
|
"""Serve `log_dir` for the duration of the run, unless switched off.
|
|
|
|
Failure is never fatal, for the same reason it is not for the live viewer:
|
|
the server is there to look at, it is not part of the run. A run that dies
|
|
because a port was taken would be a far worse trade than not seeing curves.
|
|
"""
|
|
if not getattr(args, "tensorboard", False):
|
|
yield None
|
|
return
|
|
from mjrl.viewer.tensorboard import sigterm_runs_finally, start_tensorboard
|
|
|
|
try:
|
|
tb = start_tensorboard(log_dir, scope=args.tb_scope, port=args.tb_port)
|
|
except Exception as e: # noqa: BLE001
|
|
print(f"[mjrl] tensorboard did not start, continuing without it: "
|
|
f"{type(e).__name__}: {e}")
|
|
yield None
|
|
return
|
|
|
|
print(f"[mjrl] tensorboard {tb.url} serving {tb.logdir}"
|
|
+ (f" (port {args.tb_port} was taken)" if tb.port != args.tb_port else ""))
|
|
tb.open_browser()
|
|
try:
|
|
with sigterm_runs_finally():
|
|
yield tb
|
|
finally:
|
|
tb.stop()
|