Initialize portable humanoid RL framework with licenses, locks and CI
Core and layout checks / core (push) Has been cancelled

This commit is contained in:
2026-11-03 19:46:08 +08:00
commit 7e1ff58b46
436 changed files with 64144 additions and 0 deletions
+3
View File
@@ -0,0 +1,3 @@
"""Lightweight package root: listing tasks never imports the simulator."""
__version__ = "0.2.0"
+3
View File
@@ -0,0 +1,3 @@
from universal_humanoid.cli import main
main()
+157
View File
@@ -0,0 +1,157 @@
"""Run identity, source fingerprints and atomic machine-readable evidence."""
import hashlib
import importlib.metadata
import json
import os
import subprocess
import zipfile
from datetime import datetime, timezone
from pathlib import Path
def digest(path: Path) -> str:
h = hashlib.sha256()
with path.open("rb") as stream:
for block in iter(lambda: stream.read(1024 * 1024), b""):
h.update(block)
return h.hexdigest()
def canonical_hash(value) -> str:
return hashlib.sha256(json.dumps(value, sort_keys=True, allow_nan=False).encode()).hexdigest()
def write_json(path: Path, data):
path.parent.mkdir(parents=True, exist_ok=True)
temporary = path.with_suffix(path.suffix + f".{os.getpid()}.tmp")
temporary.write_text(json.dumps(data, indent=2, sort_keys=True, allow_nan=False) + "\n")
temporary.replace(path)
def read_json(path: Path):
return json.loads(path.read_text())
def now():
return datetime.now(timezone.utc).isoformat()
def tree_hash(root: Path, suffixes=(".py",)):
files = {
str(path.relative_to(root)): digest(path)
for path in sorted(root.rglob("*"))
if path.is_file() and path.suffix.lower() in suffixes
}
return canonical_hash(files)
def git_info(path):
def git(*args):
result = subprocess.run(
["git", "-C", str(path), *args], capture_output=True, text=True, check=False
)
return result.stdout.strip() if result.returncode == 0 else None
return {"commit": git("rev-parse", "HEAD"), "status": git("status", "--short")}
def provenance(task_id: str):
import mjlab
import rsl_rl
from .backend import VENDORED_VERSIONS, project_root, require_vendored
from .registry import get_task, resolve_factory
require_vendored()
task = get_task(task_id)
mjlab_src = Path(mjlab.__file__).resolve().parent
# Include dirty and untracked Python changes, not only a misleading git HEAD.
package_root = Path(__file__).resolve().parent
factory_module = resolve_factory(task.env_factory).__module__
asset = resolve_factory(task.asset_reference)
asset_path = Path(asset() if callable(asset) else asset).resolve(strict=True)
asset_root = asset_path.parents[task.asset_root_levels - 1]
versions = dict(VENDORED_VERSIONS)
rsl_src = Path(rsl_rl.__file__).resolve().parent
root = project_root()
for name in ("torch", "mujoco", "mujoco-warp", "warp-lang"):
try:
versions[name] = importlib.metadata.version(name)
except importlib.metadata.PackageNotFoundError:
versions[name] = "unknown"
identity = {
"project_source": tree_hash(package_root, (".py", ".json")),
"mjlab_source": tree_hash(mjlab_src),
"rsl_rl_source": tree_hash(rsl_src),
"dependency_lock_sha256": digest(root / "uv.lock") if root else None,
"asset_sha256": tree_hash(asset_root, (".xml", ".stl", ".obj", ".png", ".jpg")),
"versions": versions,
}
return {
"identity": identity,
"identity_sha256": canonical_hash(identity),
"mjlab_path": str(mjlab_src),
"rsl_rl_path": str(rsl_src),
"mjlab_git": git_info(mjlab_src),
"asset_root": str(asset_root),
"factory_module": factory_module,
}
def snapshot_sources(output: Path, record: dict):
"""Preserve dirty Python sources for manual restoration in an isolated checkout.
Does not archive meshes or secrets; the external assets remain operator-owned.
Never automatically execute Python from a downloaded run archive.
"""
roots = {
"universal_humanoid": Path(__file__).resolve().parent,
"mjlab": Path(record["mjlab_path"]),
"rsl_rl": Path(record["rsl_rl_path"]),
}
destination = output / "sources.zip"
with zipfile.ZipFile(destination, "x", compression=zipfile.ZIP_DEFLATED) as archive:
for prefix, root in roots.items():
for path in sorted(root.rglob("*")):
if path.is_file() and path.suffix in (".py", ".json"):
archive.write(path, str(Path(prefix) / path.relative_to(root)))
for prefix in ("mjlab", "rsl_rl"):
root = roots[prefix]
license_path = root / "LICENSE"
if license_path.is_file():
archive.write(license_path, f"{prefix}-LICENSE")
for path in sorted((root / "licenses").rglob("*")):
if path.is_file():
archive.write(path, str(Path(prefix) / path.relative_to(root)))
from .backend import project_root
root = project_root()
if root:
for relative in ("uv.lock", "pyproject.toml", "rl/VENDOR.json"):
archive.write(root / relative, relative)
return digest(destination)
def load_run(checkpoint: Path, *, allow_incomplete=False):
checkpoint = checkpoint.resolve(strict=True)
run = read_json(checkpoint.parent / "run.json")
if run["status"] != "completed":
sealed = run.get("checkpoint_metadata", {}).get(checkpoint.name, {})
if not (allow_incomplete and sealed.get("committed") is True):
raise ValueError(
"Only completed runs or explicitly committed intermediate checkpoints allowed"
)
if canonical_hash(run["experiment"]) != run["experiment_sha256"]:
raise ValueError("Experiment hash differs from the run manifest")
recorded = run["checkpoints"].get(checkpoint.name)
if recorded != digest(checkpoint):
raise ValueError("Checkpoint hash differs from the run manifest")
current = provenance(run["experiment"]["task"])
if current["identity_sha256"] != run["provenance"]["identity_sha256"]:
raise ValueError(
"Code, assets or dependencies changed since training. Restore the recorded "
"environment; refusing silent replay with different rewards or mechanics."
)
return run
+64
View File
@@ -0,0 +1,64 @@
"""Resolve vendored backends without changing sys.path or consulting personal workspaces."""
import importlib.util
from pathlib import Path
VENDORED_VERSIONS = {"mjlab": "1.6.0+uh.1", "rsl-rl-lib": "5.5.1+uh.1"}
def project_root():
package = Path(__file__).resolve().parent
# Editable checkout versus a built wheel; both contain the same top-level packages.
candidate = package.parents[1]
return candidate if (candidate / "rl/mjlab/__init__.py").is_file() else None
def backend_origins():
root = project_root()
package_root = root / "rl" if root else Path(__file__).resolve().parent.parent
results = {}
for name in ("mjlab", "rsl_rl"):
spec = importlib.util.find_spec(name)
actual = Path(spec.origin).resolve() if spec and spec.origin else None
expected = package_root / name / "__init__.py"
results[name] = {
"actual": str(actual) if actual else None,
"expected": str(expected),
"matches": actual == expected.resolve(),
}
return results
def require_vendored():
origins = backend_origins()
if not all(item["matches"] for item in origins.values()):
raise RuntimeError(
"Backend shadowing or missing editable install. Install this project in a fresh "
"environment; do not separately install mjlab/rsl-rl-lib. Origins: " + str(origins)
)
return origins
def verify_vendor(root=None):
from .artifacts import digest, read_json
root = Path(root) if root is not None else project_root()
if root is None:
raise ValueError("Vendor source verification requires a repository checkout")
manifest = read_json(root / "rl/VENDOR.json")
actual = {
str(p.relative_to(root)): digest(p)
for p in (root / "rl").rglob("*")
if p.is_file() and "__pycache__" not in p.parts and p.name != "VENDOR.json"
}
recorded = manifest["files"]
mismatches = sorted(
key for key in actual.keys() | recorded.keys() if actual.get(key) != recorded.get(key)
)
return {
"ready": not mismatches,
"files": len(actual),
"mismatches": mismatches,
"versions": VENDORED_VERSIONS,
"manifest": str(root / "rl/VENDOR.json"),
}
+308
View File
@@ -0,0 +1,308 @@
"""Serial checkpoint × evaluation-seed × command × profile experiments."""
import csv
import statistics
from collections import defaultdict
from pathlib import Path
from .artifacts import canonical_hash, digest, load_run, now, read_json, write_json
from .evaluation import COMMANDS, profile_spec
METRICS = (
"tracking_xy_rmse_m_s",
"tracking_yaw_rmse_rad_s",
"failure_fraction_completed",
"failure_events_per_sim_second",
"first_episode_failure_fraction",
"mean_completed_seconds",
)
def moments(values):
finite = [value for value in values if value is not None]
return {
"n": len(finite),
"mean": statistics.mean(finite) if finite else None,
"variance": statistics.variance(finite) if len(finite) > 1 else None,
}
def aggregate(records):
grouped = defaultdict(list)
for record in records:
report = record["report"]
if report["status"] != "completed":
raise ValueError("Cannot aggregate unfinished evaluation")
grouped[(record["checkpoint_id"], record["profile"], record["command_name"])].append(report)
rows = []
for (checkpoint_id, profile, command), reports in sorted(grouped.items()):
seeds = [r["protocol"]["seed"] for r in reports]
if len(set(seeds)) != len(seeds):
raise ValueError("Duplicate evaluation seeds would inflate the sample count")
protocol_keys = [
canonical_hash({k: v for k, v in r["protocol"].items() if k != "seed"}) for r in reports
]
if len(set(protocol_keys)) != 1 or len({r["task"] for r in reports}) != 1:
raise ValueError("Aggregation requires identical task/protocol except seed")
rows.append(
{
"checkpoint_id": checkpoint_id,
"profile": profile,
"command": command,
"seeds": seeds,
"metrics": {k: moments([r["metrics"][k] for r in reports]) for k in METRICS},
"total_completed_episodes": sum(
r["metrics"]["completed_episodes"] for r in reports
),
"total_failure_events": sum(r["metrics"]["failure_events"] for r in reports),
"first_episode_censored_count": sum(
r["metrics"]["first_episode_censored_count"] for r in reports
),
}
)
return rows
def benchmark(checkpoints, output, *, seeds, profiles=("randomized",), steps=500, num_envs=8):
from .runtime import evaluate
if (
not seeds
or len(set(seeds)) != len(seeds)
or any(type(s) is not int or s < 0 for s in seeds)
):
raise ValueError("Provide distinct non-negative evaluation seeds")
if not profiles or len(set(profiles)) != len(profiles):
raise ValueError("Provide distinct profiles")
for profile in profiles:
profile_spec(profile)
runs = [load_run(path, allow_incomplete=True) for path in checkpoints]
if not runs or len({run["experiment"]["task"] for run in runs}) != 1:
raise ValueError("Benchmark checkpoints must have the same task")
if len({run["experiment"].get("episode_seconds", 20.0) for run in runs}) != 1:
raise ValueError("Benchmark checkpoints must have the same episode duration")
checkpoint_info = [
{
"id": f"c{i:03d}",
"path": str(path.resolve()),
"sha256": digest(path),
"training_seed": run["experiment"]["seed"],
"experiment_sha256": run["experiment_sha256"],
}
for i, (path, run) in enumerate(zip(checkpoints, runs))
]
if len({info["sha256"] for info in checkpoint_info}) != len(checkpoint_info):
raise ValueError("Duplicate checkpoints are not independent candidates")
output.mkdir(parents=True, exist_ok=False)
state = {
"schema_version": 1,
"status": "running",
"created_at": now(),
"task": runs[0]["experiment"]["task"],
"checkpoints": checkpoint_info,
"protocol": {
"seeds": seeds,
"profiles": list(profiles),
"steps": steps,
"num_envs": num_envs,
"commands": COMMANDS,
},
"completed_cells": 0,
"total_cells": len(checkpoints) * len(seeds) * len(profiles) * len(COMMANDS),
"reports": [],
"hardware_approved": False,
"statistics": (
"mean and sample variance across evaluation-seed aggregates "
"(not pooled worlds); variance is null for n<2"
),
"failure_definition": (
"completed failures / completed episodes; null if none completed. "
"Also report failure incidence per simulated world-second and "
"first-episode failure by observed horizon."
),
}
write_json(output / "summary.json", state)
records = []
try:
for path, info in zip(checkpoints, checkpoint_info):
for profile in profiles:
for command_name, command in COMMANDS.items():
for seed in seeds:
filename = f"{info['id']}-{profile}-{command_name}-seed{seed}.json"
state["current_cell"] = filename
write_json(output / "summary.json", state)
report = evaluate(
path,
output / filename,
steps=steps,
num_envs=num_envs,
command=command,
seed=seed,
profile=profile,
)
records.append(
{
"checkpoint_id": info["id"],
"profile": profile,
"command_name": command_name,
"report": report,
}
)
state["reports"].append(filename)
state["completed_cells"] += 1
write_json(output / "summary.json", state)
state["rows"] = aggregate(records)
write_table(output, state["rows"])
state["status"] = "completed"
except BaseException as error:
state.update(status="failed", error=f"{type(error).__name__}: {error}")
raise
finally:
state["updated_at"] = now()
write_json(output / "summary.json", state)
return state
def write_table(output, rows):
columns = [
"checkpoint",
"profile",
"command",
"metric",
"n",
"mean",
"sample_variance",
"completed_episodes",
"failure_events",
"first_episode_censored",
]
with (output / "table.csv").open("x", newline="") as stream:
writer = csv.writer(stream)
writer.writerow(columns)
lines = ["| " + " | ".join(columns) + " |", "|" + "---|" * len(columns)]
for row in rows:
for metric, stats in row["metrics"].items():
values = [
row["checkpoint_id"],
row["profile"],
row["command"],
metric,
stats["n"],
stats["mean"],
stats["variance"],
row["total_completed_episodes"],
row["total_failure_events"],
row["first_episode_censored_count"],
]
writer.writerow(values)
lines.append(
"| " + " | ".join("null" if v is None else str(v) for v in values) + " |"
)
(output / "table.md").write_text("\n".join(lines) + "\n")
def select_checkpoint(summary_path: Path, output: Path, metric="failure_events_per_sim_second"):
summary = read_json(summary_path)
if summary["status"] != "completed":
raise ValueError("Checkpoint selection requires a completed benchmark")
if metric not in METRICS or metric == "mean_completed_seconds":
raise ValueError("Selection requires a supported lower-is-better metric")
if output.exists():
raise FileExistsError(output)
rankings = []
expected = {(p, c) for p in summary["protocol"]["profiles"] for c in COMMANDS}
for info in summary["checkpoints"]:
rows = [row for row in summary["rows"] if row["checkpoint_id"] == info["id"]]
if {(r["profile"], r["command"]) for r in rows} != expected or len(rows) != len(expected):
raise ValueError("Incomplete checkpoint evaluation matrix")
if any(set(r["seeds"]) != set(summary["protocol"]["seeds"]) for r in rows):
raise ValueError("Incomplete seed coverage")
values = [row["metrics"][metric]["mean"] for row in rows]
if any(v is None for v in values):
raise ValueError("Cannot select using undefined metrics")
rankings.append({**info, "score": statistics.mean(values)})
rankings.sort(key=lambda row: (row["score"], row["id"]))
result = {
"status": "completed",
"metric": metric,
"aggregation": "equal weight per command/profile",
"rankings": rankings,
"selected": rankings[0],
"hardware_approved": False,
"benchmark_sha256": digest(summary_path),
"note": (
"Selection-set winner only; use held-out seeds before claiming generalization. "
"Ties break by checkpoint input order; no deployment promotion."
),
}
write_json(output, result)
return result
def compare_benchmarks(baseline_path, candidate_path):
baseline, candidate = read_json(baseline_path), read_json(candidate_path)
if (
baseline.get("status") != "completed"
or candidate.get("status") != "completed"
or baseline.get("task") != candidate.get("task")
or baseline.get("protocol") != candidate.get("protocol")
or len(baseline.get("checkpoints", [])) != 1
or len(candidate.get("checkpoints", [])) != 1
):
raise ValueError(
"Comparison needs completed single-checkpoint benchmarks with identical protocol"
)
def index(summary, path):
reports = {}
for filename in summary["reports"]:
if Path(filename).name != filename:
raise ValueError("Invalid report path")
report = read_json(path.parent / filename)
key = (
report["protocol"]["randomization"]["profile"],
tuple(report["protocol"]["command"]),
report["protocol"]["seed"],
)
if key in reports or report["status"] != "completed":
raise ValueError("Duplicate/unfinished benchmark cell")
reports[key] = report
expected = {
(p, tuple(c), seed)
for p in summary["protocol"]["profiles"]
for c in COMMANDS.values()
for seed in summary["protocol"]["seeds"]
}
if set(reports) != expected:
raise ValueError("Incomplete benchmark cells")
return reports
left, right = index(baseline, baseline_path), index(candidate, candidate_path)
groups = defaultdict(list)
for key in left:
a, b = left[key], right[key]
if a["protocol"] != b["protocol"] or a["task"] != b["task"]:
raise ValueError("Cell protocols differ")
groups[key[:2]].append(
{
metric: (
b["metrics"][metric] - a["metrics"][metric]
if a["metrics"][metric] is not None and b["metrics"][metric] is not None
else None
)
for metric in METRICS
}
)
return {
"paired_candidate_minus_baseline": [
{
"profile": profile,
"command": command,
"metrics": {m: moments([row[m] for row in rows]) for m in METRICS},
}
for (profile, command), rows in sorted(groups.items())
],
"note": (
"Paired by evaluation seed; not a significance test or independent training-seed study"
),
}
+340
View File
@@ -0,0 +1,340 @@
"""Single CLI shared by humans and coding agents; heavy imports stay lazy."""
import argparse
import json
import math
import sys
from pathlib import Path
from .artifacts import read_json, write_json
from .config import Experiment
from .registry import TASKS
def positive_int(value):
result = int(value)
if result < 1:
raise argparse.ArgumentTypeError("must be a positive integer")
return result
def finite_float(value):
result = float(value)
if not math.isfinite(result):
raise argparse.ArgumentTypeError("must be finite")
return result
def parser():
root = argparse.ArgumentParser(description="Universal Humanoid: agent-operated mjlab RL")
commands = root.add_subparsers(dest="operation", required=True)
commands.add_parser("list", help="List tasks without importing torch or mjlab")
commands.add_parser(
"doctor", help="Check installed vendored backends, locked core versions and CUDA"
)
commands.add_parser("verify-vendor", help="Verify the checked-in backend/asset inventory")
robot = commands.add_parser(
"check-robot", help="Audit sites, IMU, contact response, PD, order and pose"
)
robot.add_argument("--config", type=Path, required=True)
robot.add_argument("--output", type=Path, required=True)
robot.add_argument("--steps", type=positive_int, default=32)
robot.add_argument("--spec", type=Path, help="Explicit robot conformance specification JSON")
commands.add_parser("assets", help="Discover external humanoid MJCFs (not registered tasks)")
inspect = commands.add_parser("inspect-asset", help="Compile external MJCF with native MuJoCo")
inspect.add_argument("path", type=Path)
for name in ("plan", "rewards", "smoke", "train", "pipeline"):
cmd = commands.add_parser(name)
cmd.add_argument("--config", type=Path, required=name != "train")
if name == "train":
cmd.add_argument(
"--resume", type=Path, help="Explicit committed checkpoint; new output run"
)
cmd.add_argument(
"--iterations", type=positive_int, help="Additional updates, including on resume"
)
cmd.add_argument("--background", action="store_true")
if name in ("train", "pipeline"):
cmd.add_argument("--output", type=Path, required=True)
if name == "smoke":
cmd.add_argument("--steps", type=positive_int, default=16)
cmd.add_argument("--num-envs", type=positive_int, default=4)
if name == "pipeline":
cmd.add_argument("--eval-steps", type=positive_int, default=500)
cmd.add_argument("--eval-envs", type=positive_int, default=8)
evaluate = commands.add_parser("evaluate")
evaluate.add_argument("--checkpoint", type=Path, required=True)
evaluate.add_argument("--output", type=Path, required=True)
evaluate.add_argument("--steps", type=positive_int, default=500)
evaluate.add_argument("--num-envs", type=positive_int, default=8)
evaluate.add_argument("--command", type=finite_float, nargs=3, default=(0.3, 0.0, 0.0))
evaluate.add_argument("--video", type=Path)
evaluate.add_argument("--seed", type=int)
evaluate.add_argument(
"--profile", choices=("nominal", "randomized", "stress"), default="randomized"
)
evaluate.add_argument(
"--measure", type=Path, help="Per-step joint/torque CSV before episode reset"
)
play = commands.add_parser("play")
play.add_argument("--checkpoint", type=Path, required=True)
play.add_argument("--viewer", choices=("native", "viser"), default="native")
play.add_argument("--measure", type=Path, help="Bounded headless measured replay (CSV path)")
play.add_argument("--steps", type=positive_int, default=500)
play.add_argument("--seed", type=int)
play.add_argument(
"--profile", choices=("nominal", "randomized", "stress"), default="randomized"
)
play.add_argument("--command", type=finite_float, nargs=3, default=(0.3, 0.0, 0.0))
play.add_argument("--video", type=Path)
for name in ("status", "stop", "checkpoints"):
cmd = commands.add_parser(name)
cmd.add_argument("run", type=Path)
curves = commands.add_parser("curves", help="Read TensorBoard scalars into JSON/CSV/SVG")
curves.add_argument("run", type=Path)
curves.add_argument("--output", type=Path, required=True)
curves.add_argument("--match", help="Optional scalar tag regex")
curves.add_argument("--window", type=positive_int, default=20)
benchmark = commands.add_parser(
"benchmark", help="Checkpoints × evaluation seeds × four commands"
)
benchmark.add_argument("--checkpoints", type=Path, nargs="+", required=True)
benchmark.add_argument("--output", type=Path, required=True)
benchmark.add_argument("--seeds", type=int, nargs="+", required=True)
benchmark.add_argument(
"--profiles", choices=("nominal", "randomized", "stress"), nargs="+", default=["randomized"]
)
benchmark.add_argument("--steps", type=positive_int, default=500)
benchmark.add_argument("--num-envs", type=positive_int, default=8)
select = commands.add_parser(
"select-checkpoint", help="Rank a completed benchmark, never promote to hardware"
)
select.add_argument("summary", type=Path)
select.add_argument("--output", type=Path, required=True)
select.add_argument("--metric", default="failure_events_per_sim_second")
export = commands.add_parser("export")
export.add_argument("--checkpoint", type=Path, required=True)
export.add_argument("--evaluation", type=Path, required=True)
export.add_argument("--output", type=Path, required=True)
verify = commands.add_parser("verify-bundle")
verify.add_argument("bundle", type=Path)
verify.add_argument("--inference", action="store_true", help="Also run saved ONNX reference")
compare = commands.add_parser("compare")
compare.add_argument("baseline", type=Path)
compare.add_argument("candidate", type=Path)
return root
def run(args):
op = args.operation
if op == "list":
return [t.to_dict() for t in TASKS.values()]
if op == "verify-vendor":
from .backend import verify_vendor
return verify_vendor()
if op == "check-robot":
from .robot_check import check_robot
return check_robot(
Experiment.load(args.config), args.output, steps=args.steps, spec_path=args.spec
)
if op in ("doctor", "assets", "inspect-asset"):
from .inspection import asset_inventory, doctor, inspect_asset
if op == "doctor":
result = doctor()
if not result["ready"]:
raise RuntimeError(json.dumps(result))
return result
return asset_inventory() if op == "assets" else inspect_asset(args.path)
if op in ("status", "stop", "checkpoints"):
from .jobs import status, stop
from .training import checkpoint_listing
return {"status": status, "stop": stop, "checkpoints": checkpoint_listing}[op](args.run)
if op == "curves":
from .curves import export_curves
return export_curves(args.run, args.output, match=args.match, window=args.window)
if op == "benchmark":
from .benchmark import benchmark
return benchmark(
args.checkpoints,
args.output,
seeds=args.seeds,
profiles=args.profiles,
steps=args.steps,
num_envs=args.num_envs,
)
if op == "select-checkpoint":
from .benchmark import select_checkpoint
return select_checkpoint(args.summary, args.output, args.metric)
if op in ("plan", "rewards", "smoke", "train", "pipeline"):
if op == "train" and args.resume is not None:
from .training import resume_experiment
if args.iterations is None:
raise ValueError("Resume requires an explicit --iterations (additional updates)")
exp = (
Experiment.load(args.config)
if args.config
else resume_experiment(args.resume, args.iterations)
)
exp.iterations = args.iterations
else:
if args.config is None:
raise ValueError("--config is required for a new training run")
exp = Experiment.load(args.config)
if op == "train" and args.iterations is not None:
exp.iterations = args.iterations
exp.validate()
if op == "plan":
return {
"experiment": exp.to_dict(),
"backend": "mujoco-warp",
"task": TASKS[exp.task].to_dict(),
"hardware_approved": False,
}
if op == "rewards":
from .tasks import build_configs
cfg, _ = build_configs(exp)
return {
name: {
"weight": term.weight,
"function": f"{term.func.__module__}:{term.func.__name__}",
"parameters": {k: repr(v) for k, v in term.params.items()},
}
for name, term in cfg.rewards.items()
}
from .runtime import evaluate, smoke, train
if op == "smoke":
return smoke(exp, args.steps, args.num_envs)
if op == "train":
if args.background:
from .jobs import launch
return launch(exp, args.output, resume=args.resume)
return {"checkpoint": str(train(exp, args.output, resume=args.resume))}
# Fail before training if the workflow directory already exists.
args.output.mkdir(parents=True, exist_ok=False)
state = {"status": "running", "stage": "train", "hardware_approved": False}
state_path = args.output / "pipeline.json"
write_json(state_path, state)
try:
checkpoint = train(exp, args.output / "train")
state["stage"] = "evaluate"
write_json(state_path, state)
evaluate(
checkpoint,
args.output / "evaluation.json",
steps=args.eval_steps,
num_envs=args.eval_envs,
)
from .deployment import export_bundle
state["stage"] = "export"
write_json(state_path, state)
export_bundle(checkpoint, args.output / "evaluation.json", args.output / "bundle")
state.update(status="completed", stage="research-bundle")
except BaseException as error:
state.update(status="failed", error=f"{type(error).__name__}: {error}")
raise
finally:
write_json(state_path, state)
return state
if op == "evaluate":
from .runtime import evaluate
return evaluate(
args.checkpoint,
args.output,
steps=args.steps,
num_envs=args.num_envs,
command=tuple(args.command),
video=args.video,
seed=args.seed,
profile=args.profile,
measure=args.measure,
)
if op == "play":
if args.measure is not None:
from .runtime import evaluate
return evaluate(
args.checkpoint,
args.measure.with_suffix(".evaluation.json"),
steps=args.steps,
num_envs=1,
command=tuple(args.command),
seed=args.seed,
profile=args.profile,
measure=args.measure,
video=args.video,
)
if args.video is not None:
raise ValueError("play --video requires --measure; or use evaluate --video")
from .runtime import play
play(args.checkpoint, args.viewer)
return {"status": "viewer closed"}
if op == "export":
from .deployment import export_bundle
return {"bundle": str(export_bundle(args.checkpoint, args.evaluation, args.output))}
if op == "verify-bundle":
from .deployment import PolicyRuntime, verify_bundle
manifest = verify_bundle(args.bundle)
if args.inference:
import numpy as np
reference = read_json(args.bundle / "reference.json")
actual = PolicyRuntime(args.bundle).predict(reference["observation"])
np.testing.assert_allclose(
actual["raw_action"], reference["raw_action"], atol=1e-5, rtol=1e-4
)
return {
"integrity": True,
"inference_checked": args.inference,
"task": manifest["task"],
"hardware_approved": False,
}
if op == "compare":
baseline, candidate = read_json(args.baseline), read_json(args.candidate)
if "rows" in baseline or "rows" in candidate:
from .benchmark import compare_benchmarks
return compare_benchmarks(args.baseline, args.candidate)
if (
baseline["task"] != candidate["task"]
or baseline["protocol"] != candidate["protocol"]
or baseline["status"] != "completed"
or candidate["status"] != "completed"
):
raise ValueError("Comparison requires completed reports with identical task/protocol")
# Reward totals across differently shaped rewards are not a valid selection criterion.
keys = ("tracking_xy_rmse_m_s", "tracking_yaw_rmse_rad_s", "failure_events")
return {
"candidate_minus_baseline": {
key: candidate["metrics"][key] - baseline["metrics"][key] for key in keys
},
"note": "Lower is better; use multiple seeds and longer rollouts before promotion",
}
raise ValueError(f"Unsupported operation {op}")
def main(argv=None):
args = parser().parse_args(argv)
try:
result = run(args)
except (ValueError, FileNotFoundError, FileExistsError, RuntimeError) as error:
print(f"ERROR: {error}", file=sys.stderr)
raise SystemExit(1) from error
print(json.dumps(result, indent=2, ensure_ascii=False, allow_nan=False))
if isinstance(result, dict) and result.get("ready") is False:
raise SystemExit(1)
+90
View File
@@ -0,0 +1,90 @@
"""Strict, JSON-serializable experiment specification, independent of mjlab."""
import json
import math
from dataclasses import asdict, dataclass, field
from pathlib import Path
from .registry import get_task
@dataclass
class Experiment:
task: str = "g1.flat"
seed: int = 42
num_envs: int = 256
iterations: int = 1000
steps_per_env: int = 24
checkpoint_interval: int = 50
episode_seconds: float = 20.0
device: str = "cuda:0"
action_clip: float = 5.0
reward_weights: dict[str, float] = field(default_factory=dict)
reward_params: dict[str, dict] = field(default_factory=dict)
extra_rewards: dict[str, dict] = field(default_factory=dict)
def validate(self):
get_task(self.task)
for name in ("num_envs", "iterations", "steps_per_env", "checkpoint_interval"):
value = getattr(self, name)
if type(value) is not int or value < 1:
raise ValueError(f"{name} must be a positive integer")
if type(self.seed) is not int or self.seed < 0:
raise ValueError("seed must be a non-negative integer")
for name in ("episode_seconds", "action_clip"):
value = getattr(self, name)
if not finite_number(value) or value <= 0:
raise ValueError(f"{name} must be finite and positive")
if not isinstance(self.device, str) or not self.device.startswith("cuda:"):
raise ValueError("Training runtime requires an explicit CUDA device, e.g. cuda:0")
if not self.device[5:].isdigit():
raise ValueError("Invalid CUDA device index")
if self.num_envs * self.steps_per_env < 4:
raise ValueError("PPO needs at least four samples for its four minibatches")
for name in ("reward_weights", "reward_params", "extra_rewards"):
if not isinstance(getattr(self, name), dict):
raise ValueError(f"{name} must be an object")
for name, value in self.reward_weights.items():
if not finite_number(value):
raise ValueError(f"Non-finite reward weight: {name}")
for name, params in self.reward_params.items():
if not isinstance(params, dict):
raise ValueError(f"Reward parameters must be an object: {name}")
validate_json_numbers(params)
for name, term in self.extra_rewards.items():
if not isinstance(term, dict) or set(term) - {"function", "weight", "params"}:
raise ValueError(f"Invalid extra reward: {name}")
if not isinstance(term.get("function"), str) or not finite_number(term.get("weight")):
raise ValueError(f"Extra reward needs function and finite weight: {name}")
if not isinstance(term.get("params", {}), dict):
raise ValueError(f"Extra reward params must be an object: {name}")
validate_json_numbers(term.get("params", {}))
return self
def to_dict(self):
return asdict(self)
@classmethod
def load(cls, path: str | Path):
data = json.loads(Path(path).read_text())
if not isinstance(data, dict):
raise ValueError("Experiment must be a JSON object")
unknown = set(data) - set(cls.__dataclass_fields__)
if unknown:
raise ValueError(f"Unknown experiment keys: {sorted(unknown)}")
return cls(**data).validate()
def finite_number(value):
return type(value) in (int, float) and math.isfinite(value)
def validate_json_numbers(value):
if isinstance(value, dict):
for item in value.values():
validate_json_numbers(item)
elif isinstance(value, list):
for item in value:
validate_json_numbers(item)
elif isinstance(value, float) and not math.isfinite(value):
raise ValueError("NaN/Infinity are not valid reward parameters")
+170
View File
@@ -0,0 +1,170 @@
"""Read TensorBoard scalars without a server and emit curves, not time-spent claims."""
import csv
import html
import math
import re
import statistics
from pathlib import Path
from .artifacts import write_json
CATEGORIES = {
"tracking": r"(?i)(track|error_vel)",
"action_noise": r"(?i)(mean_std|action_std)",
"episode_length": r"(?i)(episode_length|episode_time)",
"reward": r"^Train/mean_reward$",
"curriculum": r"^Curriculum/",
}
def series_summary(points, window):
values = [p["value"] for p in points]
tail = points[-window:]
if not values:
return {"count": 0}
xs = [p["step"] for p in tail]
ys = [p["value"] for p in tail]
center = statistics.mean(xs)
denominator = sum((x - center) ** 2 for x in xs)
slope = (
sum((x - center) * (y - statistics.mean(ys)) for x, y in zip(xs, ys)) / denominator
if denominator
else None
)
return {
"count": len(values),
"first": values[0],
"last": values[-1],
"min": min(values),
"max": max(values),
"tail_mean": statistics.mean(ys),
"tail_slope_per_iteration": slope,
"tail_points": len(tail),
}
def read_curves(log_dir: Path, *, match=None, window=20):
from tensorboard.backend.event_processing.event_accumulator import EventAccumulator
if window < 1:
raise ValueError("window must be positive")
if not log_dir.is_dir() or not list(log_dir.glob("events.out.tfevents.*")):
raise FileNotFoundError(f"No TensorBoard event files directly in {log_dir}")
accumulator = EventAccumulator(str(log_dir), size_guidance={"scalars": 0})
accumulator.Reload()
available = sorted(accumulator.Tags().get("scalars", []))
try:
expression = re.compile(match) if match else None
except re.error as error:
raise ValueError(f"Invalid scalar-tag regex: {error}") from error
selected = [
tag
for tag in available
if (
expression.search(tag)
if expression
else not tag.endswith("/time")
and any(re.search(pattern, tag) for pattern in CATEGORIES.values())
)
]
series = {}
for tag in selected:
by_step = {}
rejected = 0
for point in accumulator.Scalars(tag):
if not math.isfinite(point.value):
rejected += 1
continue
previous = by_step.get(point.step)
if previous is None or point.wall_time >= previous["wall_time"]:
by_step[point.step] = {
"step": point.step,
"wall_time": point.wall_time,
"value": point.value,
}
points = [by_step[key] for key in sorted(by_step)]
summary = series_summary(points, window)
axis = "elapsed_seconds" if tag.endswith("/time") else "iteration"
if axis == "elapsed_seconds" and points:
summary["tail_slope_per_second"] = summary.pop("tail_slope_per_iteration")
series[tag] = {
"points": points,
"summary": summary,
"step_axis": axis,
"nonfinite_points": rejected,
}
missing = [
name
for name, pattern in CATEGORIES.items()
if not any(re.search(pattern, tag) for tag in series)
]
return {
"log_dir": str(log_dir.resolve()),
"available_tags": available,
"series": series,
"missing_categories": missing,
"window": window,
"note": (
"Latest wall-time wins duplicate steps. Missing episode scalars may mean no "
"completed episodes. Trends are evidence to inspect, not an automatic "
"convergence verdict."
),
}
def write_svg(path, series):
# No matplotlib/GUI dependency. Each scalar gets its own labelled axes.
width, height = 900, max(1, len(series)) * 220
parts = [
f'<svg xmlns="http://www.w3.org/2000/svg" width="{width}" height="{height}">',
'<rect width="100%" height="100%" fill="white"/>',
]
for panel, (tag, data) in enumerate(series.items()):
top = panel * 220
parts.append(f'<text x="20" y="{top + 20}" font-size="14">{html.escape(tag)}</text>')
points = data["points"]
if not points:
continue
xmin, xmax = points[0]["step"], points[-1]["step"]
ymin, ymax = min(p["value"] for p in points), max(p["value"] for p in points)
coordinates = " ".join(
f"{90 + 760 * (p['step'] - xmin) / max(1, xmax - xmin):.2f},"
f"{top + 170 - 130 * (p['value'] - ymin) / (ymax - ymin or 1):.2f}"
for p in points
)
parts.extend(
[
f'<path d="M90 {top + 35} V{top + 175} H850" fill="none" stroke="gray"/>',
f'<polyline points="{coordinates}" fill="none" stroke="#1769aa" stroke-width="2"/>',
f'<text x="5" y="{top + 45}" font-size="11">{ymax:.4g}</text>',
f'<text x="5" y="{top + 170}" font-size="11">{ymin:.4g}</text>',
f'<text x="90" y="{top + 200}" font-size="12">'
f"{data.get('step_axis', 'iteration')} {xmin} → {xmax}</text>",
]
)
if not series:
parts.append('<text x="20" y="40">No matching scalar curves</text>')
parts.append("</svg>")
path.write_text("\n".join(parts))
def export_curves(log_dir, output, *, match=None, window=20):
result = read_curves(log_dir, match=match, window=window)
output.mkdir(parents=True, exist_ok=False)
write_json(output / "curves.json", result)
with (output / "curves.csv").open("x", newline="") as stream:
writer = csv.writer(stream)
writer.writerow(["tag", "step", "step_axis", "wall_time", "value"])
for tag, series in result["series"].items():
for point in series["points"]:
writer.writerow(
[tag, point["step"], series["step_axis"], point["wall_time"], point["value"]]
)
write_svg(output / "curves.svg", result["series"])
return {
"output": str(output),
"curves": {k: v["summary"] for k, v in result["series"].items()},
"missing_categories": result["missing_categories"],
"note": result["note"],
}
+253
View File
@@ -0,0 +1,253 @@
"""Research-only ONNX bundles; deliberately no robot bus or power-on API."""
import math
import shutil
import tempfile
from dataclasses import asdict
from pathlib import Path
from .artifacts import digest, load_run, now, read_json, write_json
from .config import Experiment
def _vector(value, size):
if isinstance(value, (float, int)):
return [float(value)] * size
return value[0].detach().cpu().tolist()
def build_contract(env, agent_cfg):
"""Extract ordering and transforms from the BUILT environment, never regex order."""
import mujoco
raw = env.unwrapped
action = raw.action_manager.get_term("joint_pos")
robot = raw.scene["robot"]
model = raw.sim.mj_model
names = action.target_names
motors = []
for name in names:
joint_id = mujoco.mj_name2id(model, mujoco.mjtObj.mjOBJ_JOINT, "robot/" + name)
ids = [i for i in range(model.nu) if model.actuator_trnid[i, 0] == joint_id]
if joint_id < 0 or len(ids) != 1:
raise ValueError(f"Need one actuator per named joint for export: {name}")
i = ids[0]
motors.append(
{
"joint": name,
"kp": float(model.actuator_gainprm[i, 0]),
"kd": float(-model.actuator_biasprm[i, 2]),
"effort_range": model.actuator_forcerange[i].tolist(),
"joint_range": model.jnt_range[joint_id].tolist(),
"gear": model.actuator_gear[i].tolist(),
}
)
terms = []
manager = raw.observation_manager
offset = 0
for name, shape in zip(manager.active_terms["actor"], manager.group_obs_term_dim["actor"]):
cfg = manager.get_term_cfg("actor", name)
size = math.prod(shape)
terms.append(
{
"name": name,
"shape": list(shape),
"start": offset,
"stop": offset + size,
"function": f"{cfg.func.__module__}:{cfg.func.__name__}",
"scale": cfg.scale,
"clip": cfg.clip,
}
)
offset += size
if action.cfg.clip is not None:
raise ValueError("Per-joint action clip requires a new bundle schema")
return {
"schema_version": 1,
"kind": "research-policy",
"hardware_approved": False,
"control": {
"physics_dt": raw.physics_dt,
"policy_dt": raw.step_dt,
"decimation": raw.cfg.decimation,
"motors": motors,
},
"observation": {
"size": offset,
"terms": terms,
"joint_names": list(robot.joint_names),
"joint_position_reference": robot.data.default_joint_pos[0].cpu().tolist(),
"joint_velocity_reference": robot.data.default_joint_vel[0].cpu().tolist(),
"frame": "body; gravity is unit world-down expressed in body frame",
"command": "vx [m/s], vy [m/s], yaw_rate [rad/s]",
"previous_action": "previous clipped raw policy action; zeros after reset",
"normalization": "embedded in policy.onnx; do not normalize twice",
"base_velocity": "requires a validated base velocity estimator on hardware",
},
"action": {
"size": len(names),
"joint_names": list(names),
"raw_clip": agent_cfg.clip_actions,
"scale": _vector(action.scale, len(names)),
"offset": _vector(action.offset, len(names)),
"formula": "target_rad = clip(raw, -raw_clip, raw_clip) * scale + offset",
"encoder_bias": "zero in nominal inference; calibrate externally on hardware",
},
"limitations": [
"PD gains are simulation settings, not a certified hardware controller",
"No bus mapping, watchdog, state estimator, emergency stop or joint-limit supervisor",
"A finite rollout and ONNX parity do not demonstrate learned locomotion",
],
}
def export_bundle(checkpoint: Path, evaluation: Path, output: Path):
import numpy as np
import onnx
import onnxruntime as ort
import torch
from .runtime import make_env, make_runner
run = load_run(checkpoint)
report = read_json(evaluation)
if (
report.get("status") != "completed"
or report.get("checkpoint_sha256") != digest(checkpoint)
or report.get("experiment_sha256") != run["experiment_sha256"]
or report.get("identity_sha256") != run["provenance"]["identity_sha256"]
):
raise ValueError("Evaluation must match this checkpoint, experiment and source identity")
if output.exists():
raise FileExistsError(output)
exp = Experiment(**run["experiment"]).validate()
env, agent_cfg = make_env(exp, evaluation=True, num_envs=1, command=(0.3, 0, 0))
output.parent.mkdir(parents=True, exist_ok=True)
temporary = Path(tempfile.mkdtemp(prefix=".bundle-", dir=output.parent))
try:
runner = make_runner(env, agent_cfg)
runner.load(str(checkpoint), load_cfg={"actor": True}, map_location=exp.device)
contract = build_contract(env, agent_cfg)
policy = runner.get_inference_policy(device=exp.device)
# Gather real observations before export moves the copied ONNX network to CPU.
observations, references = [], []
obs, _ = env.reset()
with torch.inference_mode():
for _ in range(16):
actions = policy(obs)
observations.append(obs["actor"].cpu().numpy().copy())
references.append(actions.cpu().numpy().copy())
obs, _, _, _ = env.step(actions)
runner.export_policy_to_onnx(str(temporary))
onnx.checker.check_model(onnx.load(str(temporary / "policy.onnx")))
session = ort.InferenceSession(
str(temporary / "policy.onnx"), providers=["CPUExecutionProvider"]
)
input_name = session.get_inputs()[0].name
errors = []
for observation, expected in zip(observations, references):
actual = session.run(None, {input_name: observation})[0]
np.testing.assert_allclose(actual, expected, atol=1e-5, rtol=1e-4)
errors.append(float(np.max(np.abs(actual - expected))))
contract["onnx"] = {
"input_name": input_name,
"output_name": session.get_outputs()[0].name,
"batch_size": 1,
"dtype": "float32",
}
write_json(temporary / "contract.json", contract)
write_json(temporary / "evaluation.json", report)
write_json(temporary / "experiment.json", exp.to_dict())
write_json(temporary / "provenance.json", run["provenance"])
write_json(temporary / "agent.json", asdict(agent_cfg))
write_json(
temporary / "reference.json",
{"observation": observations[0].tolist(), "raw_action": references[0].tolist()},
)
write_json(
temporary / "manifest.json",
{
"schema_version": 1,
"created_at": now(),
"task": exp.task,
"checkpoint_sha256": digest(checkpoint),
"hardware_approved": False,
"onnx_parity": {"samples": len(errors), "max_abs_error": max(errors)},
"files": {p.name: digest(p) for p in sorted(temporary.iterdir()) if p.is_file()},
},
)
verify_bundle(temporary)
temporary.rename(output)
finally:
env.close()
if temporary.exists():
shutil.rmtree(temporary)
return output
def verify_bundle(bundle: Path):
manifest = read_json(bundle / "manifest.json")
if manifest.get("schema_version") != 1 or manifest.get("hardware_approved") is not False:
raise ValueError("Unsupported bundle schema or unsafe hardware approval")
files = manifest.get("files", {})
required = {
"policy.onnx",
"contract.json",
"evaluation.json",
"reference.json",
"experiment.json",
"provenance.json",
"agent.json",
}
if not required.issubset(files):
raise ValueError("Incomplete bundle")
for name, expected in files.items():
if Path(name).name != name or name in (".", ".."):
raise ValueError("Bundle manifest contains a non-local path")
path = bundle / name
if path.is_symlink() or digest(path) != expected:
raise ValueError(f"Bundle integrity failure: {name}")
contract = read_json(bundle / "contract.json")
if contract.get("hardware_approved") is not False or contract.get("schema_version") != 1:
raise ValueError("Unsafe or unsupported controller contract")
action = contract["action"]
if not (
len(action["joint_names"])
== len(action["scale"])
== len(action["offset"])
== action["size"]
== len(set(action["joint_names"]))
):
raise ValueError("Action contract lengths or joint names are invalid")
return manifest
class PolicyRuntime:
"""Inference only: consumes preassembled observations and returns joint targets.
No physical transport is implemented. Caller owns observation assembly and
must reset previous actions on episode boundaries. This is not a safety layer.
"""
def __init__(self, bundle: Path):
import onnxruntime as ort
verify_bundle(bundle)
self.contract = read_json(bundle / "contract.json")
self.session = ort.InferenceSession(
str(bundle / "policy.onnx"), providers=["CPUExecutionProvider"]
)
def predict(self, observation):
import numpy as np
value = np.asarray(observation, dtype=np.float32)
if value.shape != (1, self.contract["observation"]["size"]) or not np.isfinite(value).all():
raise ValueError("Expected a finite float32 observation of shape [1, observation_size]")
result = self.session.run(None, {self.contract["onnx"]["input_name"]: value})[0]
cfg = self.contract["action"]
if result.shape != (1, cfg["size"]) or not np.isfinite(result).all():
raise ValueError("Non-finite or invalid policy output")
clipped = np.clip(result, -cfg["raw_clip"], cfg["raw_clip"])
targets = clipped * np.asarray(cfg["scale"]) + np.asarray(cfg["offset"])
return {"raw_action": result, "clipped_action": clipped, "joint_targets": targets}
+122
View File
@@ -0,0 +1,122 @@
"""Versioned evaluation profiles and observable, per-world randomized resets."""
import copy
PROFILES = ("nominal", "randomized", "stress")
COMMANDS = {
"stand": (0.0, 0.0, 0.0),
"forward": (0.3, 0.0, 0.0),
"lateral": (0.0, 0.2, 0.0),
"turn": (0.0, 0.0, 0.3),
}
def profile_spec(name):
if name not in PROFILES:
raise ValueError(f"Unknown evaluation profile: {name}")
randomized = name != "nominal"
return {
"profile": name,
"reset_pose_range": (
{
"x": (-0.1, 0.1),
"y": (-0.1, 0.1),
"z": (0.01, 0.03),
"roll": (-0.03, 0.03),
"pitch": (-0.03, 0.03),
"yaw": (-0.2, 0.2),
}
if randomized
else {"z": (0.02, 0.02)}
),
"reset_velocity_range": (
{"x": (-0.05, 0.05), "y": (-0.05, 0.05), "yaw": (-0.1, 0.1)} if randomized else {}
),
"joint_position_offset_rad": (-0.03, 0.03) if randomized else (0.0, 0.0),
"joint_velocity_offset_rad_s": (-0.1, 0.1) if randomized else (0.0, 0.0),
"actor_observation_noise": name == "stress",
"push_interval_seconds": (0.5, 1.5) if name == "stress" else None,
"push_velocity_delta": (
{"x": (-0.4, 0.4), "y": (-0.4, 0.4), "yaw": (-0.5, 0.5)} if name == "stress" else None
),
"push_model": "instantaneous additive root velocity kick, not a physical force",
"startup_domain_randomization": False,
}
def counted_push(env, env_ids, velocity_range):
import torch
from mjlab.envs.mdp.events import push_by_setting_velocity
if env_ids is None:
env_ids = torch.arange(env.num_envs, device=env.device)
if not hasattr(env, "uh_push_counts"):
env.uh_push_counts = torch.zeros(env.num_envs, device=env.device, dtype=torch.long)
env.uh_push_counts[env_ids] += 1
push_by_setting_velocity(env, env_ids, velocity_range=velocity_range)
def configure_evaluation(env, name):
from mjlab.managers.event_manager import EventTermCfg
spec = profile_spec(name)
# Explicit whitelist: do not accidentally retain a new training randomizer.
env.events = {key: env.events[key] for key in ("reset_base", "reset_robot_joints")}
env.events["reset_base"].params["pose_range"] = copy.deepcopy(spec["reset_pose_range"])
env.events["reset_base"].params["velocity_range"] = copy.deepcopy(spec["reset_velocity_range"])
env.events["reset_robot_joints"].params.update(
position_range=spec["joint_position_offset_rad"],
velocity_range=spec["joint_velocity_offset_rad_s"],
)
for key, group in env.observations.items():
group.enable_corruption = key == "actor" and spec["actor_observation_noise"]
if name == "stress":
env.events["evaluation_push"] = EventTermCfg(
func=counted_push,
mode="interval",
interval_range_s=spec["push_interval_seconds"],
params={"velocity_range": spec["push_velocity_delta"]},
)
def initial_state_evidence(raw):
"""Store actual initial states, relative to world origin, not just a RNG seed."""
import torch
robot = raw.scene["robot"]
state = (
torch.cat(
(
robot.data.root_link_pos_w - raw.scene.env_origins,
robot.data.root_link_quat_w,
robot.data.root_link_vel_w,
robot.data.joint_pos,
robot.data.joint_vel,
),
dim=1,
)
.detach()
.cpu()
)
return {
"columns": [
"root_x",
"root_y",
"root_z",
"qw",
"qx",
"qy",
"qz",
"vx",
"vy",
"vz",
"wx",
"wy",
"wz",
]
+ [f"q/{n}" for n in robot.joint_names]
+ [f"dq/{n}" for n in robot.joint_names],
"worlds": state.tolist(),
"unique_states": int(torch.unique(state, dim=0).shape[0]),
"sampling": "per-world uniform draws on each reset; shared policy, not training replicas",
}
+105
View File
@@ -0,0 +1,105 @@
"""Read-only installed-backend, runtime and optional external-asset inspection."""
import importlib.metadata
import os
import sys
from pathlib import Path
from .backend import VENDORED_VERSIONS, backend_origins, project_root
ROOTS = {"booster": "BOOSTER_ASSETS_ROOT", "unitree": "UNITREE_ROBOTS_ROOT"}
def asset_inventory():
result = []
for source, variable in ROOTS.items():
configured = os.environ.get(variable)
if not configured:
continue # No assumption about an operator's HOME directory.
root = Path(configured).expanduser()
patterns = (
("robots/T1/*.xml", "robots/T2/**/*.xml", "robots/K1/**/*.xml")
if source == "booster"
else ("g1*/*.xml", "h1*/**/*.xml", "h2*/*.xml", "r1*/*.xml")
)
for pattern in patterns:
for path in sorted(root.glob(pattern)):
if path.name != "package.xml":
result.append(
{
"source": source,
"path": str(path),
"status": "discovered-only; not an RL adapter",
}
)
return result
def inspect_asset(path: Path):
import mujoco
model = mujoco.MjModel.from_xml_path(str(path.resolve()))
return {
"path": str(path.resolve()),
"nq": model.nq,
"nv": model.nv,
"nu": model.nu,
"joints": [model.joint(i).name for i in range(model.njnt)],
"actuators": [model.actuator(i).name for i in range(model.nu)],
"status": (
"MuJoCo-compiled only; use check-robot for a registered task's conformance checks"
),
}
def doctor():
import torch
import warp
origins = backend_origins()
versions = dict(VENDORED_VERSIONS)
for package in ("mujoco", "mujoco-warp", "warp-lang", "torch"):
versions[package] = importlib.metadata.version(package)
conflicts = []
for name in VENDORED_VERSIONS:
try:
importlib.metadata.distribution(name)
conflicts.append(name)
except importlib.metadata.PackageNotFoundError:
pass
root = project_root()
lock_mismatches = {}
if root:
import tomllib
lock = tomllib.loads((root / "uv.lock").read_text())
# Check installed members of the lock; absent optional/other-Python branches
# are not errors. setup-env's dependency gate separately checks missing requirements.
locked = {}
for package in lock["package"]:
locked.setdefault(package["name"], set()).add(package["version"])
for distribution in importlib.metadata.distributions():
name = distribution.metadata["Name"].lower().replace("_", "-")
if name in locked and distribution.version not in locked[name]:
lock_mismatches[name] = {
"installed": distribution.version,
"locked": sorted(locked[name]),
}
warp.init()
cuda = torch.cuda.is_available()
return {
"python": sys.executable,
"backends": origins,
"versions": versions,
"conflicting_distributions": conflicts,
"lock_mismatches": lock_mismatches,
"cuda_available": cuda,
"devices": [torch.cuda.get_device_name(i) for i in range(torch.cuda.device_count())],
"warp_devices": [str(x) for x in warp.get_devices()],
"ready": all(o["matches"] for o in origins.values())
and cuda
and warp.is_cuda_available()
and not conflicts
and not lock_mismatches,
"note": "Vendored backend and bundled G1/T1 assets; no external mjlab checkout required",
}
+129
View File
@@ -0,0 +1,129 @@
"""Local Linux background jobs with PID-reuse guards and durable status files."""
import os
import signal
import subprocess
import sys
from datetime import datetime, timezone
from pathlib import Path
from .artifacts import now, read_json, write_json
def job_directory(output):
return output.resolve().with_name(output.name + ".job")
def process_identity(pid):
try:
# comm can contain spaces and parentheses; parse after its final ')'.
stat = Path(f"/proc/{pid}/stat").read_text().rsplit(")", 1)[1].split()
if stat[0] == "Z":
return None
return {
"pid": pid,
"start_ticks": stat[19],
"boot_id": Path("/proc/sys/kernel/random/boot_id").read_text().strip(),
}
except (FileNotFoundError, ProcessLookupError):
return None
def launch(exp, output, *, resume=None):
if not sys.platform.startswith("linux"):
raise ValueError("Managed background jobs currently require Linux /proc")
output = output.resolve()
if output.exists():
raise FileExistsError(output)
job = job_directory(output)
job.mkdir(parents=True, exist_ok=False)
spec = {
"experiment": exp.to_dict(),
"output": str(output),
"resume": str(resume.resolve()) if resume else None,
}
write_json(job / "spec.json", spec)
write_json(job / "state.json", {"status": "queued", "updated_at": now()})
environment = os.environ.copy()
# The selected interpreter must have the project installed, including vendored packages.
environment.pop("PYTHONPATH", None)
environment["PYTHONNOUSERSITE"] = "1"
try:
with (job / "stdout.log").open("xb") as log:
child = subprocess.Popen(
[sys.executable, "-u", "-m", "universal_humanoid.worker", str(job)],
stdin=subprocess.DEVNULL,
stdout=log,
stderr=subprocess.STDOUT,
start_new_session=True,
env=environment,
)
identity = process_identity(child.pid)
write_json(job / "launch.json", {"identity": identity, "launched_at": now()})
except BaseException as error:
write_json(
job / "state.json", {"status": "failed", "error": str(error), "updated_at": now()}
)
raise
return {
"status": "launched",
"pid": child.pid,
"run": str(output),
"job": str(job),
"log": str(job / "stdout.log"),
"note": "Local process, not a reboot-persistent scheduler",
}
def status(output):
output = output.resolve()
job = job_directory(output)
result = {"run": str(output)}
if (job / "state.json").exists():
result["job"] = read_json(job / "state.json")
launch_record = read_json(job / "launch.json") if (job / "launch.json").exists() else {}
identity = launch_record.get("identity")
result["process_alive"] = bool(identity and process_identity(identity["pid"]) == identity)
if not result["process_alive"] and result["job"]["status"] in ("running", "queued"):
result["effective_status"] = "lost" if launch_record else "launching"
else:
result["effective_status"] = result["job"]["status"]
if (output / "run.json").exists():
record = read_json(output / "run.json")
result["training_status"] = record["status"]
result.setdefault("effective_status", record["status"])
identity = record.get("process_identity")
if "process_alive" not in result and identity:
result["process_alive"] = process_identity(identity["pid"]) == identity
if not result["process_alive"] and record["status"] in ("training", "initializing"):
result["effective_status"] = "lost"
result["checkpoints"] = record["checkpoints"]
if (output / "progress.json").exists():
result["progress"] = read_json(output / "progress.json")
updated = datetime.fromisoformat(result["progress"]["updated_at"])
result["seconds_since_update"] = (datetime.now(timezone.utc) - updated).total_seconds()
if len(result) == 1:
raise FileNotFoundError(f"No training/job state for {output}")
return result
def stop(output):
job = job_directory(output)
identity = read_json(job / "launch.json").get("identity")
if not identity or process_identity(identity["pid"]) != identity:
raise ValueError("Job is no longer alive or its PID identity changed; refusing to signal")
# pidfd binds the signal to this process even if it exits and the PID is reused.
if not hasattr(os, "pidfd_open") or not hasattr(signal, "pidfd_send_signal"):
raise ValueError("Safe stop requires Linux pidfd support")
fd = os.pidfd_open(identity["pid"])
try:
if process_identity(identity["pid"]) != identity:
raise ValueError("Process identity changed; refusing to signal")
signal.pidfd_send_signal(fd, signal.SIGTERM)
finally:
os.close(fd)
return {
"status": "stop-requested",
"run": str(output),
"note": "Poll status for interrupted/failed; resume the latest committed checkpoint",
}
+86
View File
@@ -0,0 +1,86 @@
"""Long-form per-control-step measurement, sampled before resetting terminal worlds."""
import csv
from .artifacts import write_json
class JointRecorder:
def __init__(self, path, env):
self.path = path
raw = env.unwrapped
self.robot = raw.scene["robot"]
self.term = raw.action_manager.get_term("joint_pos")
self.names = list(self.term.target_names)
self.indices = [list(self.robot.joint_names).index(n) for n in self.names]
self.clip = env.clip_actions
path.parent.mkdir(parents=True, exist_ok=True)
self.stream = path.open("x", newline="")
self.writer = csv.writer(self.stream)
self.writer.writerow(
[
"step",
"time_s",
"world",
"episode",
"episode_time_s",
"terminated",
"timeout",
"joint",
"position_rad",
"velocity_rad_s",
"actuator_joint_torque_nm",
"raw_action",
"applied_action",
"target_rad",
]
)
self.rows = 0
self.metadata = {
"status": "recording",
"sample_phase": "post-control-step, before any episode reset",
"torque": (
"qfrc_actuator projected to joint DOFs, instantaneous endpoint; "
"not a decimation average"
),
"timing": "policy-rate samples; interval velocity kicks occur before this sample",
"policy_dt": raw.step_dt,
"joint_names": self.names,
"hardware_approved": False,
}
write_json(path.with_suffix(path.suffix + ".json"), self.metadata)
def record(self, step, dt, episodes, lengths, terminated, timeout, actions):
import torch
robot = self.robot
q = robot.data.joint_pos[:, self.indices]
dq = robot.data.joint_vel[:, self.indices]
tau = robot.data.qfrc_actuator[:, self.indices]
applied = actions.clamp(-self.clip, self.clip) if self.clip is not None else actions
# Action transform is read from the live term, including its resolved ordering.
target = robot.data.joint_pos_target[:, self.indices]
values = torch.stack((q, dq, tau, actions, applied, target), dim=-1).detach().cpu()
if not torch.isfinite(values).all():
raise FloatingPointError("Non-finite joint measurement")
for world, joints in enumerate(values.tolist()):
for index, row in enumerate(joints):
self.writer.writerow(
[
step,
(step + 1) * dt,
world,
int(episodes[world]),
float(lengths[world]) * dt,
int(terminated[world]),
int(timeout[world]),
self.names[index],
*row,
]
)
self.rows += 1
def close(self, completed):
self.stream.close()
self.metadata.update(status="completed" if completed else "failed", rows=self.rows)
write_json(self.path.with_suffix(self.path.suffix + ".json"), self.metadata)
+59
View File
@@ -0,0 +1,59 @@
"""Metadata-only robot/task registry. Factories are loaded only on demand."""
from dataclasses import asdict, dataclass
from importlib import import_module
@dataclass(frozen=True)
class Task:
id: str
robot: str
dof: int
env_factory: str
rl_factory: str
asset_source: str
asset_reference: str
asset_root_levels: int
status: str = "simulation-adapter"
def to_dict(self):
return asdict(self)
TASKS = {
task.id: task
for task in (
Task(
"g1.flat",
"unitree_g1",
29,
"mjlab.tasks.velocity.config.g1.env_cfgs:unitree_g1_flat_env_cfg",
"mjlab.tasks.velocity.config.g1.rl_cfg:unitree_g1_ppo_runner_cfg",
"mjlab/asset_zoo/robots/unitree_g1 (NOT the unitree_ros variant)",
"mjlab.asset_zoo.robots.unitree_g1.g1_constants:G1_XML",
2,
),
Task(
"t1.flat",
"booster_t1",
23,
"mjlab.tasks.velocity.config.booster_t1.env_cfgs:booster_t1_flat_env_cfg",
"mjlab.tasks.velocity.config.booster_t1.rl_cfg:booster_t1_ppo_runner_cfg",
"Bundled T1_23dof.xml (optional BOOSTER_ASSETS_ROOT override)",
"mjlab.asset_zoo.robots.booster_t1.t1_constants:get_t1_xml",
1,
),
)
}
def get_task(task_id: str) -> Task:
try:
return TASKS[task_id]
except KeyError:
raise ValueError(f"Unknown task {task_id!r}; choose {', '.join(TASKS)}") from None
def resolve_factory(reference: str):
module, name = reference.split(":", 1)
return getattr(import_module(module), name)
+28
View File
@@ -0,0 +1,28 @@
"""Agent-editable, batched reward mechanisms; tuning belongs in experiments.
Add a function here and explicitly register it in FUNCTIONS. JSON cannot import
arbitrary Python. Each reward must return one finite scalar per environment.
"""
import torch
def planar_velocity_exp(env, std: float, command_name: str = "twist"):
"""Track planar body-frame speed, without penalizing vertical velocity."""
if std <= 0:
raise ValueError("std must be positive")
command = env.command_manager.get_command(command_name)
velocity = env.scene["robot"].data.root_link_lin_vel_b
error = (command[:, :2] - velocity[:, :2]).square().sum(dim=-1)
return torch.exp(-error / std**2)
def joint_speed_l2(env):
"""Joint-speed regularizer; assign a negative weight in the experiment."""
return env.scene["robot"].data.joint_vel.square().sum(dim=-1)
FUNCTIONS = {
"planar_velocity_exp": planar_velocity_exp,
"joint_speed_l2": joint_speed_l2,
}
+400
View File
@@ -0,0 +1,400 @@
"""One-command adapter conformance: declared semantics plus measured contact/PD response."""
import math
from pathlib import Path
from .artifacts import now, read_json, write_json
from .registry import get_task
CHECK_IDS = (
"free_root",
"foot_sites",
"imu",
"joint_order",
"pd_and_limits",
"action_transform",
"initial_pose",
"initial_penetration",
"contact_configuration",
"contact_response",
"finite_probe",
)
def load_spec(task, path=None):
path = path or Path(__file__).parent / "robot_specs" / f"{get_task(task).robot}.json"
spec = read_json(path)
if spec.get("schema_version") != 1 or spec.get("task") != task:
raise ValueError("Robot check spec must have schema_version=1 and match the selected task")
required = {
"action_joint_order",
"observation_joint_order",
"default_joint_position_rad",
"default_root_position_m",
"default_root_quaternion_wxyz",
"foot_sites",
"foot_site_positions_m",
"foot_site_quaternions_wxyz",
"imu_site",
"imu_body",
"imu_site_position_m",
"imu_site_quaternion_wxyz",
"imu_sensors",
"contact_sensor",
"contact_bodies",
"motors",
"action_scale",
"action_offset",
"policy_dt",
"physics_dt",
"max_initial_penetration_m",
}
from .config import validate_json_numbers
validate_json_numbers(spec)
missing = required - set(spec)
if missing:
raise ValueError(f"Missing robot check spec fields: {sorted(missing)}")
if not spec["foot_sites"] or not spec["imu_sensors"] or not spec["contact_bodies"]:
raise ValueError("Foot sites, IMU sensors and contact bodies must be explicitly declared")
for key in ("foot_site_positions_m", "foot_site_quaternions_wxyz"):
if set(spec[key]) != set(spec["foot_sites"]):
raise ValueError(f"{key} must cover every declared foot site")
return spec
def close(a, b, tolerance=1e-5):
if isinstance(a, (list, tuple)) and isinstance(b, (list, tuple)):
return len(a) == len(b) and all(close(x, y, tolerance) for x, y in zip(a, b))
return (
type(a) in (int, float)
and type(b) in (int, float)
and math.isfinite(a)
and math.isfinite(b)
and abs(a - b) <= tolerance
)
def assess(spec, facts):
"""Pure checks; tests can corrupt one semantic at a time without requiring CUDA."""
checks = []
def add(name, passed, evidence):
checks.append({"id": name, "passed": bool(passed), "evidence": evidence})
add("free_root", facts["free_root_count"] == 1, facts["free_root_count"])
sites = facts["foot_sites"]
add(
"foot_sites",
all(
sites.get(n, {}).get("body") == body
and sites[n].get("height_m") is not None
and -0.015 <= sites[n]["height_m"] <= 0.3
and close(sites[n].get("local_position_m"), spec["foot_site_positions_m"][n])
and close(sites[n].get("local_quaternion"), spec["foot_site_quaternions_wxyz"][n])
for n, body in spec["foot_sites"].items()
),
sites,
)
imu = facts["imu"]
add(
"imu",
all(
imu.get(n, {}).get("type") == kind
and imu[n].get("site") == spec["imu_site"]
and imu[n].get("dimension") == 3
and imu[n].get("body") == spec["imu_body"]
and close(imu[n].get("site_position_m"), spec["imu_site_position_m"])
and close(imu[n].get("site_quaternion"), spec["imu_site_quaternion_wxyz"])
for n, kind in spec["imu_sensors"].items()
),
imu,
)
add(
"joint_order",
facts["action_joint_order"] == spec["action_joint_order"]
and facts["observation_joint_order"] == spec["observation_joint_order"]
and len(set(facts["action_joint_order"])) == len(facts["action_joint_order"]),
{"action": facts["action_joint_order"], "observation": facts["observation_joint_order"]},
)
motors = facts["motors"]
valid = len(motors) == len(spec["motors"])
for expected in spec["motors"]:
motor = motors.get(expected["joint"], {})
valid &= (
motor.get("count") == 1
and motor.get("joint_transmission") is True
and motor.get("force_limited") is True
and motor.get("joint_limited") is True
and motor.get("hinge_joint") is True
and motor.get("kp", 0) > 0
and motor.get("kd", -1) >= 0
)
valid &= all(
close(motor.get(key), expected[key])
for key in ("kp", "kd", "effort_range", "joint_range", "gear")
)
add("pd_and_limits", valid, motors)
transform = facts["action_transform"]
add(
"action_transform",
all(
close(transform[k], spec[k])
for k in ("action_scale", "action_offset", "policy_dt", "physics_dt")
),
transform,
)
pose = facts["initial_pose"]
add(
"initial_pose",
close(pose["default_joint_position"], spec["default_joint_position_rad"])
and close(pose["actual_joint_position"], pose["default_joint_position"])
and close(pose["default_root_position"], spec["default_root_position_m"])
and close(pose["default_root_quaternion"], spec["default_root_quaternion_wxyz"])
and close(pose["actual_root_quaternion"], spec["default_root_quaternion_wxyz"])
and close(
pose["actual_root_position"],
[v + (0.02 if i == 2 else 0) for i, v in enumerate(spec["default_root_position_m"])],
)
and close(pose["actual_joint_velocity"], [0.0] * len(spec["observation_joint_order"]))
and close(pose["actual_root_velocity"], [0.0] * 6)
and pose["within_joint_limits"]
and pose["upright_cosine"] > 0.98,
pose,
)
add(
"initial_penetration",
facts["initial_penetration_m"] <= spec["max_initial_penetration_m"],
facts["initial_penetration_m"],
)
contact = facts["contacts"]
add(
"contact_configuration",
contact["bodies"] == spec["contact_bodies"]
and contact["terrain_filter"]
and contact["has_force_and_found"]
and all(contact["collision_enabled"].get(n, False) for n in spec["contact_bodies"]),
contact,
)
add(
"contact_response",
all(contact["observed"].get(n, False) for n in spec["contact_bodies"])
and all(contact["peak_force_n"].get(n, 0) > 0 for n in spec["contact_bodies"]),
{"observed": contact["observed"], "peak_force_n": contact["peak_force_n"]},
)
add(
"finite_probe",
facts["probe"]["finite"] and facts["probe"]["terminations"] == 0,
facts["probe"],
)
return checks
def gather(env, spec, steps):
import mujoco
import numpy as np
import torch
raw = env.unwrapped
model = raw.sim.mj_model
robot = raw.scene["robot"]
action = raw.action_manager.get_term("joint_pos")
def lookup(kind, name):
return mujoco.mj_name2id(model, kind, "robot/" + name)
def short(name):
return name.removeprefix("robot/") if name else name
sites = {}
for name in spec["foot_sites"]:
i = lookup(mujoco.mjtObj.mjOBJ_SITE, name)
if i >= 0:
sites[name] = {
"body": short(model.body(model.site_bodyid[i]).name),
"local_position_m": model.site_pos[i].tolist(),
"local_quaternion": model.site_quat[i].tolist(),
"height_m": float(
raw.sim.data.site_xpos[0, i, 2].item() - raw.scene.env_origins[0, 2].item()
),
}
imu = {}
types = {
int(mujoco.mjtSensor.mjSENS_GYRO): "gyro",
int(mujoco.mjtSensor.mjSENS_VELOCIMETER): "velocimeter",
int(mujoco.mjtSensor.mjSENS_ACCELEROMETER): "accelerometer",
}
for name in spec["imu_sensors"]:
i = lookup(mujoco.mjtObj.mjOBJ_SENSOR, name)
if i >= 0 and model.sensor_objtype[i] == mujoco.mjtObj.mjOBJ_SITE:
site = model.sensor_objid[i]
imu[name] = {
"type": types.get(int(model.sensor_type[i]), "other"),
"dimension": int(model.sensor_dim[i]),
"site": short(model.site(site).name),
"site_quaternion": model.site_quat[site].tolist(),
"site_position_m": model.site_pos[site].tolist(),
"body": short(model.body(model.site_bodyid[site]).name),
}
motors = {}
within_limits = True
actual_q = robot.data.joint_pos[0].detach().cpu().tolist()
for name in action.target_names:
joint = lookup(mujoco.mjtObj.mjOBJ_JOINT, name)
ids = [i for i in range(model.nu) if model.actuator_trnid[i, 0] == joint]
entry = {"count": len(ids)}
if len(ids) == 1 and joint >= 0:
i = ids[0]
entry.update(
kp=float(model.actuator_gainprm[i, 0]),
kd=float(-model.actuator_biasprm[i, 2]),
force_limited=bool(model.actuator_forcelimited[i]),
joint_limited=bool(model.jnt_limited[joint]),
hinge_joint=bool(model.jnt_type[joint] == mujoco.mjtJoint.mjJNT_HINGE),
joint_transmission=bool(model.actuator_trntype[i] == mujoco.mjtTrn.mjTRN_JOINT),
effort_range=model.actuator_forcerange[i].tolist(),
joint_range=model.jnt_range[joint].tolist(),
gear=model.actuator_gear[i].tolist(),
)
q = actual_q[list(robot.joint_names).index(name)]
within_limits &= model.jnt_range[joint, 0] <= q <= model.jnt_range[joint, 1]
motors[name] = entry
native = mujoco.MjData(model)
native.qpos[:] = raw.sim.data.qpos[0].detach().cpu().numpy()
native.qvel[:] = raw.sim.data.qvel[0].detach().cpu().numpy()
mujoco.mj_forward(model, native)
penetration = max([0.0] + [-float(c.dist) for c in native.contact[: native.ncon]])
default = robot.data.default_root_state[0].detach().cpu().tolist()
def vector(value):
return (
[float(value)] * len(action.target_names)
if isinstance(value, (int, float))
else value[0].detach().cpu().tolist()
)
sensor = raw.scene.sensors.get(spec["contact_sensor"])
bodies = sensor.primary_names if sensor is not None else []
contacts = {
"bodies": bodies,
"terrain_filter": bool(
sensor is not None
and sensor.cfg.secondary is not None
and sensor.cfg.secondary.pattern == "terrain"
),
"has_force_and_found": bool(
sensor is not None and {"force", "found"} <= set(sensor.cfg.fields)
),
"collision_enabled": {},
"observed": dict.fromkeys(bodies, False),
"peak_force_n": dict.fromkeys(bodies, 0.0),
}
for name in spec["contact_bodies"]:
body = lookup(mujoco.mjtObj.mjOBJ_BODY, name)
ids = [i for i in range(model.ngeom) if model.geom_bodyid[i] == body]
contacts["collision_enabled"][name] = any(
model.geom_contype[i] or model.geom_conaffinity[i] for i in ids
)
facts = {
"free_root_count": int(np.sum(model.jnt_type == mujoco.mjtJoint.mjJNT_FREE)),
"foot_sites": sites,
"imu": imu,
"action_joint_order": list(action.target_names),
"observation_joint_order": list(robot.joint_names),
"motors": motors,
"action_transform": {
"action_scale": vector(action.scale),
"action_offset": vector(action.offset),
"physics_dt": raw.physics_dt,
"policy_dt": raw.step_dt,
},
"initial_pose": {
"default_joint_position": robot.data.default_joint_pos[0].cpu().tolist(),
"actual_joint_position": actual_q,
"actual_joint_velocity": robot.data.joint_vel[0].cpu().tolist(),
"actual_root_position": (robot.data.root_link_pos_w[0] - raw.scene.env_origins[0])
.cpu()
.tolist(),
"actual_root_quaternion": robot.data.root_link_quat_w[0].cpu().tolist(),
"actual_root_velocity": robot.data.root_link_vel_w[0].cpu().tolist(),
"default_root_position": default[:3],
"default_root_quaternion": default[3:7],
"within_joint_limits": bool(within_limits),
"upright_cosine": float(-robot.data.projected_gravity_b[0, 2].item()),
},
"initial_penetration_m": penetration,
"contacts": contacts,
"probe": {
"requested_steps": steps,
"completed_steps": 0,
"finite": True,
"terminations": 0,
},
}
with torch.inference_mode():
for _ in range(steps):
obs, rewards, done, _ = env.step(torch.zeros((1, env.num_actions), device=raw.device))
facts["probe"]["completed_steps"] += 1
finite = all(
torch.isfinite(x).all().item()
for x in (*obs.values(), rewards, robot.data.qfrc_actuator, robot.data.joint_pos)
)
if sensor is not None and contacts["has_force_and_found"]:
found, force = sensor.data.found, sensor.data.force
finite &= bool(torch.isfinite(force).all())
for i, name in enumerate(bodies):
slots = slice(i * sensor.cfg.num_slots, (i + 1) * sensor.cfg.num_slots)
contacts["observed"][name] |= bool((found[0, slots] > 0).any())
contacts["peak_force_n"][name] = max(
contacts["peak_force_n"][name],
float(force[0, slots].norm(dim=-1).max().item()),
)
facts["probe"]["finite"] &= finite
facts["probe"]["terminations"] += int(done.sum().item())
if done.any() or not finite:
break
return facts
def check_robot(exp, output, *, steps=32, spec_path=None):
from .runtime import make_env
if output.exists():
raise FileExistsError(output)
if steps < 1:
raise ValueError("steps must be positive")
spec = load_spec(exp.task, spec_path)
env = None
report = {
"schema_version": 1,
"task": exp.task,
"created_at": now(),
"status": "failed",
"ready": False,
"checks": [],
"hardware_approved": False,
"note": (
"Adapter conformance and bounded zero-action probe, "
"not balance/locomotion or hardware approval"
),
}
try:
env, _ = make_env(
exp,
evaluation=True,
num_envs=1,
command=(0, 0, 0),
profile="nominal",
manual_reset=True,
)
facts = gather(env, spec, steps)
report["checks"] = assess(spec, facts)
report["ready"] = all(c["passed"] for c in report["checks"])
report["status"] = "completed" if report["ready"] else "failed"
except (ValueError, RuntimeError, KeyError, FileNotFoundError) as error:
report["error"] = f"{type(error).__name__}: {error}"
finally:
write_json(output, report)
if env is not None:
env.close()
return report
@@ -0,0 +1,653 @@
{
"schema_version": 1,
"task": "t1.flat",
"action_joint_order": [
"aahead_yaw_joint",
"aahead_pitch_joint",
"left_shoulder_pitch_joint",
"left_shoulder_roll_joint",
"left_elbow_pitch_joint",
"left_elbow_yaw_joint",
"right_shoulder_pitch_joint",
"right_shoulder_roll_joint",
"right_elbow_pitch_joint",
"right_elbow_yaw_joint",
"waist_yaw_joint",
"left_hip_pitch_joint",
"left_hip_roll_joint",
"left_hip_yaw_joint",
"left_knee_pitch_joint",
"left_ankle_pitch_joint",
"left_ankle_roll_joint",
"right_hip_pitch_joint",
"right_hip_roll_joint",
"right_hip_yaw_joint",
"right_knee_pitch_joint",
"right_ankle_pitch_joint",
"right_ankle_roll_joint"
],
"observation_joint_order": [
"aahead_yaw_joint",
"aahead_pitch_joint",
"left_shoulder_pitch_joint",
"left_shoulder_roll_joint",
"left_elbow_pitch_joint",
"left_elbow_yaw_joint",
"right_shoulder_pitch_joint",
"right_shoulder_roll_joint",
"right_elbow_pitch_joint",
"right_elbow_yaw_joint",
"waist_yaw_joint",
"left_hip_pitch_joint",
"left_hip_roll_joint",
"left_hip_yaw_joint",
"left_knee_pitch_joint",
"left_ankle_pitch_joint",
"left_ankle_roll_joint",
"right_hip_pitch_joint",
"right_hip_roll_joint",
"right_hip_yaw_joint",
"right_knee_pitch_joint",
"right_ankle_pitch_joint",
"right_ankle_roll_joint"
],
"default_joint_position_rad": [
0.0,
0.0,
0.20000000298023224,
-1.2999999523162842,
0.0,
-0.4000000059604645,
0.20000000298023224,
1.2999999523162842,
0.0,
0.4000000059604645,
0.0,
-0.20000000298023224,
0.0,
0.0,
0.4000000059604645,
-0.20000000298023224,
0.0,
-0.20000000298023224,
0.0,
0.0,
0.4000000059604645,
-0.20000000298023224,
0.0
],
"default_root_position_m": [
0,
0,
0.6811
],
"default_root_quaternion_wxyz": [
1,
0,
0,
0
],
"foot_sites": {
"left_foot": "left_ankle_roll_link",
"right_foot": "right_ankle_roll_link"
},
"foot_site_positions_m": {"left_foot": [0.0101079, 0.0, -0.0432508], "right_foot": [0.0101079, 0.0, -0.0432508]},
"foot_site_quaternions_wxyz": {"left_foot": [1, 0, 0, 0], "right_foot": [1, 0, 0, 0]},
"imu_site": "imu",
"imu_body": "trunk",
"imu_site_position_m": [0.0, 0.0, 0.0],
"imu_site_quaternion_wxyz": [
1,
0,
0,
0
],
"imu_sensors": {
"imu_ang_vel": "gyro",
"imu_lin_vel": "velocimeter"
},
"contact_sensor": "feet_ground_contact",
"contact_bodies": [
"left_ankle_roll_link",
"right_ankle_roll_link"
],
"motors": [
{
"effort_range": [
-7.0,
7.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "aahead_yaw_joint",
"joint_range": [
-1.309,
1.309
],
"kd": 0.5,
"kp": 5.0
},
{
"effort_range": [
-7.0,
7.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "aahead_pitch_joint",
"joint_range": [
-0.35,
0.96
],
"kd": 0.5,
"kp": 5.0
},
{
"effort_range": [
-38.3,
38.3
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_shoulder_pitch_joint",
"joint_range": [
-3.276,
1.196
],
"kd": 2.0,
"kp": 40.0
},
{
"effort_range": [
-38.3,
38.3
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_shoulder_roll_joint",
"joint_range": [
-1.623,
1.736
],
"kd": 2.0,
"kp": 40.0
},
{
"effort_range": [
-38.3,
38.3
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_elbow_pitch_joint",
"joint_range": [
-2.235,
2.235
],
"kd": 2.0,
"kp": 40.0
},
{
"effort_range": [
-38.3,
38.3
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_elbow_yaw_joint",
"joint_range": [
-2.077,
1.658
],
"kd": 2.0,
"kp": 40.0
},
{
"effort_range": [
-38.3,
38.3
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_shoulder_pitch_joint",
"joint_range": [
-3.276,
1.196
],
"kd": 2.0,
"kp": 40.0
},
{
"effort_range": [
-38.3,
38.3
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_shoulder_roll_joint",
"joint_range": [
-1.736,
1.623
],
"kd": 2.0,
"kp": 40.0
},
{
"effort_range": [
-38.3,
38.3
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_elbow_pitch_joint",
"joint_range": [
-2.235,
2.235
],
"kd": 2.0,
"kp": 40.0
},
{
"effort_range": [
-38.3,
38.3
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_elbow_yaw_joint",
"joint_range": [
-1.658,
2.077
],
"kd": 2.0,
"kp": 40.0
},
{
"effort_range": [
-68.0,
68.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "waist_yaw_joint",
"joint_range": [
-1.012,
1.012
],
"kd": 3.0,
"kp": 100.0
},
{
"effort_range": [
-98.8,
98.8
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_hip_pitch_joint",
"joint_range": [
-2.967,
2.191
],
"kd": 5.0,
"kp": 200.0
},
{
"effort_range": [
-68.0,
68.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_hip_roll_joint",
"joint_range": [
-0.363,
1.536
],
"kd": 4.0,
"kp": 150.0
},
{
"effort_range": [
-68.0,
68.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_hip_yaw_joint",
"joint_range": [
-1.076,
1.062
],
"kd": 3.0,
"kp": 100.0
},
{
"effort_range": [
-130.5,
130.5
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_knee_pitch_joint",
"joint_range": [
0.0,
2.145
],
"kd": 5.0,
"kp": 200.0
},
{
"effort_range": [
-73.1,
73.1
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_ankle_pitch_joint",
"joint_range": [
-0.87,
0.35
],
"kd": 2.0,
"kp": 50.0
},
{
"effort_range": [
-17.2,
17.2
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_ankle_roll_joint",
"joint_range": [
-0.44,
0.44
],
"kd": 1.0,
"kp": 20.0
},
{
"effort_range": [
-98.8,
98.8
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_hip_pitch_joint",
"joint_range": [
-2.967,
2.191
],
"kd": 5.0,
"kp": 200.0
},
{
"effort_range": [
-68.0,
68.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_hip_roll_joint",
"joint_range": [
-1.536,
0.363
],
"kd": 4.0,
"kp": 150.0
},
{
"effort_range": [
-68.0,
68.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_hip_yaw_joint",
"joint_range": [
-1.076,
1.062
],
"kd": 3.0,
"kp": 100.0
},
{
"effort_range": [
-130.5,
130.5
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_knee_pitch_joint",
"joint_range": [
0.0,
2.145
],
"kd": 5.0,
"kp": 200.0
},
{
"effort_range": [
-73.1,
73.1
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_ankle_pitch_joint",
"joint_range": [
-0.87,
0.35
],
"kd": 2.0,
"kp": 50.0
},
{
"effort_range": [
-17.2,
17.2
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_ankle_roll_joint",
"joint_range": [
-0.44,
0.44
],
"kd": 1.0,
"kp": 20.0
}
],
"action_scale": [
0.3499999940395355,
0.3499999940395355,
0.23937499523162842,
0.23937499523162842,
0.23937499523162842,
0.23937499523162842,
0.23937499523162842,
0.23937499523162842,
0.23937499523162842,
0.23937499523162842,
0.17000000178813934,
0.12349999696016312,
0.1133333370089531,
0.17000000178813934,
0.16312499344348907,
0.36550000309944153,
0.2150000035762787,
0.12349999696016312,
0.1133333370089531,
0.17000000178813934,
0.16312499344348907,
0.36550000309944153,
0.2150000035762787
],
"action_offset": [
0.0,
0.0,
0.20000000298023224,
-1.2999999523162842,
0.0,
-0.4000000059604645,
0.20000000298023224,
1.2999999523162842,
0.0,
0.4000000059604645,
0.0,
-0.20000000298023224,
0.0,
0.0,
0.4000000059604645,
-0.20000000298023224,
0.0,
-0.20000000298023224,
0.0,
0.0,
0.4000000059604645,
-0.20000000298023224,
0.0
],
"policy_dt": 0.02,
"physics_dt": 0.005,
"max_initial_penetration_m": 0.015,
"reference": "Declared baseline adapter contract; changes require review, not automatic regeneration"
}
@@ -0,0 +1,809 @@
{
"schema_version": 1,
"task": "g1.flat",
"action_joint_order": [
"left_hip_pitch_joint",
"left_hip_roll_joint",
"left_hip_yaw_joint",
"left_knee_joint",
"left_ankle_pitch_joint",
"left_ankle_roll_joint",
"right_hip_pitch_joint",
"right_hip_roll_joint",
"right_hip_yaw_joint",
"right_knee_joint",
"right_ankle_pitch_joint",
"right_ankle_roll_joint",
"waist_yaw_joint",
"waist_roll_joint",
"waist_pitch_joint",
"left_shoulder_pitch_joint",
"left_shoulder_roll_joint",
"left_shoulder_yaw_joint",
"left_elbow_joint",
"left_wrist_roll_joint",
"left_wrist_pitch_joint",
"left_wrist_yaw_joint",
"right_shoulder_pitch_joint",
"right_shoulder_roll_joint",
"right_shoulder_yaw_joint",
"right_elbow_joint",
"right_wrist_roll_joint",
"right_wrist_pitch_joint",
"right_wrist_yaw_joint"
],
"observation_joint_order": [
"left_hip_pitch_joint",
"left_hip_roll_joint",
"left_hip_yaw_joint",
"left_knee_joint",
"left_ankle_pitch_joint",
"left_ankle_roll_joint",
"right_hip_pitch_joint",
"right_hip_roll_joint",
"right_hip_yaw_joint",
"right_knee_joint",
"right_ankle_pitch_joint",
"right_ankle_roll_joint",
"waist_yaw_joint",
"waist_roll_joint",
"waist_pitch_joint",
"left_shoulder_pitch_joint",
"left_shoulder_roll_joint",
"left_shoulder_yaw_joint",
"left_elbow_joint",
"left_wrist_roll_joint",
"left_wrist_pitch_joint",
"left_wrist_yaw_joint",
"right_shoulder_pitch_joint",
"right_shoulder_roll_joint",
"right_shoulder_yaw_joint",
"right_elbow_joint",
"right_wrist_roll_joint",
"right_wrist_pitch_joint",
"right_wrist_yaw_joint"
],
"default_joint_position_rad": [
-0.31200000643730164,
0.0,
0.0,
0.6690000295639038,
-0.3630000054836273,
0.0,
-0.31200000643730164,
0.0,
0.0,
0.6690000295639038,
-0.3630000054836273,
0.0,
0.0,
0.0,
0.0,
0.20000000298023224,
0.20000000298023224,
0.0,
0.6000000238418579,
0.0,
0.0,
0.0,
0.20000000298023224,
-0.20000000298023224,
0.0,
0.6000000238418579,
0.0,
0.0,
0.0
],
"default_root_position_m": [
0,
0,
0.76
],
"default_root_quaternion_wxyz": [
1,
0,
0,
0
],
"foot_sites": {
"left_foot": "left_ankle_roll_link",
"right_foot": "right_ankle_roll_link"
},
"foot_site_positions_m": {"left_foot": [0.04, 0.0, -0.037], "right_foot": [0.04, 0.0, -0.037]},
"foot_site_quaternions_wxyz": {"left_foot": [1, 0, 0, 0], "right_foot": [1, 0, 0, 0]},
"imu_site": "imu_in_pelvis",
"imu_body": "pelvis",
"imu_site_position_m": [0.04525, 0.0, -0.08339],
"imu_site_quaternion_wxyz": [
1,
0,
0,
0
],
"imu_sensors": {
"imu_ang_vel": "gyro",
"imu_lin_vel": "velocimeter"
},
"contact_sensor": "feet_ground_contact",
"contact_bodies": [
"left_ankle_roll_link",
"right_ankle_roll_link"
],
"motors": [
{
"effort_range": [
-88.0,
88.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_hip_pitch_joint",
"joint_range": [
-2.5307,
2.8798
],
"kd": 2.557889775413375,
"kp": 40.17923863450712
},
{
"effort_range": [
-139.0,
139.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_hip_roll_joint",
"joint_range": [
-0.5236,
2.9671
],
"kd": 6.308801853496639,
"kp": 99.09842777666111
},
{
"effort_range": [
-88.0,
88.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_hip_yaw_joint",
"joint_range": [
-2.7576,
2.7576
],
"kd": 2.557889775413375,
"kp": 40.17923863450712
},
{
"effort_range": [
-139.0,
139.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_knee_joint",
"joint_range": [
-0.087267,
2.8798
],
"kd": 6.308801853496639,
"kp": 99.09842777666111
},
{
"effort_range": [
-50.0,
50.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_ankle_pitch_joint",
"joint_range": [
-0.87267,
0.5236
],
"kd": 1.814445686584846,
"kp": 28.50124619574858
},
{
"effort_range": [
-50.0,
50.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_ankle_roll_joint",
"joint_range": [
-0.2618,
0.2618
],
"kd": 1.814445686584846,
"kp": 28.50124619574858
},
{
"effort_range": [
-88.0,
88.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_hip_pitch_joint",
"joint_range": [
-2.5307,
2.8798
],
"kd": 2.557889775413375,
"kp": 40.17923863450712
},
{
"effort_range": [
-139.0,
139.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_hip_roll_joint",
"joint_range": [
-2.9671,
0.5236
],
"kd": 6.308801853496639,
"kp": 99.09842777666111
},
{
"effort_range": [
-88.0,
88.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_hip_yaw_joint",
"joint_range": [
-2.7576,
2.7576
],
"kd": 2.557889775413375,
"kp": 40.17923863450712
},
{
"effort_range": [
-139.0,
139.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_knee_joint",
"joint_range": [
-0.087267,
2.8798
],
"kd": 6.308801853496639,
"kp": 99.09842777666111
},
{
"effort_range": [
-50.0,
50.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_ankle_pitch_joint",
"joint_range": [
-0.87267,
0.5236
],
"kd": 1.814445686584846,
"kp": 28.50124619574858
},
{
"effort_range": [
-50.0,
50.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_ankle_roll_joint",
"joint_range": [
-0.2618,
0.2618
],
"kd": 1.814445686584846,
"kp": 28.50124619574858
},
{
"effort_range": [
-88.0,
88.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "waist_yaw_joint",
"joint_range": [
-2.618,
2.618
],
"kd": 2.557889775413375,
"kp": 40.17923863450712
},
{
"effort_range": [
-50.0,
50.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "waist_roll_joint",
"joint_range": [
-0.52,
0.52
],
"kd": 1.814445686584846,
"kp": 28.50124619574858
},
{
"effort_range": [
-50.0,
50.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "waist_pitch_joint",
"joint_range": [
-0.52,
0.52
],
"kd": 1.814445686584846,
"kp": 28.50124619574858
},
{
"effort_range": [
-25.0,
25.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_shoulder_pitch_joint",
"joint_range": [
-3.0892,
2.6704
],
"kd": 0.907222843292423,
"kp": 14.25062309787429
},
{
"effort_range": [
-25.0,
25.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_shoulder_roll_joint",
"joint_range": [
-1.5882,
2.2515
],
"kd": 0.907222843292423,
"kp": 14.25062309787429
},
{
"effort_range": [
-25.0,
25.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_shoulder_yaw_joint",
"joint_range": [
-2.618,
2.618
],
"kd": 0.907222843292423,
"kp": 14.25062309787429
},
{
"effort_range": [
-25.0,
25.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_elbow_joint",
"joint_range": [
-1.0472,
2.0944
],
"kd": 0.907222843292423,
"kp": 14.25062309787429
},
{
"effort_range": [
-25.0,
25.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_wrist_roll_joint",
"joint_range": [
-1.97222,
1.97222
],
"kd": 0.907222843292423,
"kp": 14.25062309787429
},
{
"effort_range": [
-5.0,
5.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_wrist_pitch_joint",
"joint_range": [
-1.61443,
1.61443
],
"kd": 1.06814150219,
"kp": 16.77832748089279
},
{
"effort_range": [
-5.0,
5.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "left_wrist_yaw_joint",
"joint_range": [
-1.61443,
1.61443
],
"kd": 1.06814150219,
"kp": 16.77832748089279
},
{
"effort_range": [
-25.0,
25.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_shoulder_pitch_joint",
"joint_range": [
-3.0892,
2.6704
],
"kd": 0.907222843292423,
"kp": 14.25062309787429
},
{
"effort_range": [
-25.0,
25.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_shoulder_roll_joint",
"joint_range": [
-2.2515,
1.5882
],
"kd": 0.907222843292423,
"kp": 14.25062309787429
},
{
"effort_range": [
-25.0,
25.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_shoulder_yaw_joint",
"joint_range": [
-2.618,
2.618
],
"kd": 0.907222843292423,
"kp": 14.25062309787429
},
{
"effort_range": [
-25.0,
25.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_elbow_joint",
"joint_range": [
-1.0472,
2.0944
],
"kd": 0.907222843292423,
"kp": 14.25062309787429
},
{
"effort_range": [
-25.0,
25.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_wrist_roll_joint",
"joint_range": [
-1.97222,
1.97222
],
"kd": 0.907222843292423,
"kp": 14.25062309787429
},
{
"effort_range": [
-5.0,
5.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_wrist_pitch_joint",
"joint_range": [
-1.61443,
1.61443
],
"kd": 1.06814150219,
"kp": 16.77832748089279
},
{
"effort_range": [
-5.0,
5.0
],
"gear": [
1.0,
0.0,
0.0,
0.0,
0.0,
0.0
],
"joint": "right_wrist_yaw_joint",
"joint_range": [
-1.61443,
1.61443
],
"kd": 1.06814150219,
"kp": 16.77832748089279
}
],
"action_scale": [
0.5475464463233948,
0.3506614565849304,
0.5475464463233948,
0.3506614565849304,
0.4385773241519928,
0.4385773241519928,
0.5475464463233948,
0.3506614565849304,
0.5475464463233948,
0.3506614565849304,
0.4385773241519928,
0.4385773241519928,
0.5475464463233948,
0.4385773241519928,
0.4385773241519928,
0.4385773241519928,
0.4385773241519928,
0.4385773241519928,
0.4385773241519928,
0.4385773241519928,
0.07450087368488312,
0.07450087368488312,
0.4385773241519928,
0.4385773241519928,
0.4385773241519928,
0.4385773241519928,
0.4385773241519928,
0.07450087368488312,
0.07450087368488312
],
"action_offset": [
-0.31200000643730164,
0.0,
0.0,
0.6690000295639038,
-0.3630000054836273,
0.0,
-0.31200000643730164,
0.0,
0.0,
0.6690000295639038,
-0.3630000054836273,
0.0,
0.0,
0.0,
0.0,
0.20000000298023224,
0.20000000298023224,
0.0,
0.6000000238418579,
0.0,
0.0,
0.0,
0.20000000298023224,
-0.20000000298023224,
0.0,
0.6000000238418579,
0.0,
0.0,
0.0
],
"policy_dt": 0.02,
"physics_dt": 0.005,
"max_initial_penetration_m": 0.015,
"reference": "Declared baseline adapter contract; changes require review, not automatic regeneration"
}
+304
View File
@@ -0,0 +1,304 @@
"""Bounded simulation, randomized evaluation and viewer operations."""
import math
from dataclasses import asdict, replace
from pathlib import Path
from .artifacts import digest, load_run, now, write_json
from .config import Experiment
from .evaluation import initial_state_evidence, profile_spec
from .registry import get_task
from .tasks import build_configs
from .training import train as train
def make_env(
exp,
*,
evaluation=False,
num_envs=None,
command=None,
video=False,
profile="nominal",
manual_reset=False,
):
import torch
from mjlab.envs import ManagerBasedRlEnv
from mjlab.rl import RslRlVecEnvWrapper
from mjlab.utils.torch import configure_torch_backends
if not torch.cuda.is_available():
raise RuntimeError("CUDA is unavailable; Warp CPU is not a training fallback")
configure_torch_backends()
cfg, agent_cfg = build_configs(
exp, evaluation=evaluation, num_envs=num_envs, command=command, profile=profile
)
if manual_reset:
cfg.auto_reset = False
env = ManagerBasedRlEnv(cfg=cfg, device=exp.device, render_mode="rgb_array" if video else None)
wrapped = RslRlVecEnvWrapper(env, clip_actions=agent_cfg.clip_actions)
if wrapped.num_actions != get_task(exp.task).dof:
wrapped.close()
raise ValueError("Robot action dimension does not match registry; inspect the adapter")
return wrapped, agent_cfg
def make_runner(env, agent_cfg, log_dir=None):
from mjlab.rl import MjlabOnPolicyRunner
return MjlabOnPolicyRunner(
env, asdict(agent_cfg), str(log_dir) if log_dir else None, env.unwrapped.device
)
def smoke(exp: Experiment, steps: int, num_envs: int):
import torch
env, _ = make_env(exp, num_envs=num_envs)
try:
obs = env.get_observations()
resets = 0
for _ in range(steps):
actions = torch.zeros((num_envs, env.num_actions), device=exp.device)
obs, rewards, done, _ = env.step(actions)
if not torch.isfinite(rewards).all() or any(
not torch.isfinite(value).all() for value in obs.values()
):
raise FloatingPointError("Non-finite observation or reward")
resets += int(done.sum().item())
return {
"task": exp.task,
"steps": steps,
"num_envs": num_envs,
"actions": env.num_actions,
"observations": {k: list(v.shape) for k, v in obs.items()},
"resets": resets,
"finite": True,
"backend": "mujoco-warp",
"note": "Zero-action plumbing check, not evidence of learned locomotion",
}
finally:
env.close()
def evaluate(
checkpoint: Path,
output: Path,
*,
steps=500,
num_envs=8,
command=(0.3, 0.0, 0.0),
video: Path | None = None,
seed=None,
profile="randomized",
measure: Path | None = None,
):
import torch
from tensordict import TensorDict
spec = profile_spec(profile)
if type(steps) is not int or steps < 1 or type(num_envs) is not int or num_envs < 1:
raise ValueError("steps and num_envs must be positive integers")
if len(command) != 3 or not all(math.isfinite(v) for v in command):
raise ValueError("command must contain three finite values")
destinations = [p.resolve() for p in (output, video, measure) if p is not None]
if measure is not None:
destinations.append(measure.with_suffix(measure.suffix + ".json").resolve())
if len(set(destinations)) != len(destinations):
raise ValueError("Report, video and measurement paths must be distinct")
for path in destinations:
if path.exists():
raise FileExistsError(path)
run = load_run(checkpoint, allow_incomplete=True)
exp = Experiment(**run["experiment"]).validate()
evaluation_seed = exp.seed if seed is None else seed
eval_exp = replace(exp, seed=evaluation_seed).validate()
env, agent_cfg = make_env(
eval_exp,
evaluation=True,
num_envs=num_envs,
command=command,
video=video is not None,
profile=profile,
manual_reset=True,
)
writer = recorder = None
completed = False
try:
raw = env.unwrapped
runner = make_runner(env, agent_cfg)
runner.load(str(checkpoint), load_cfg={"actor": True}, map_location=exp.device)
raw.common_step_counter = 0
policy = runner.get_inference_policy(device=exp.device)
observation, _ = raw.reset(seed=evaluation_seed)
obs = TensorDict(observation, batch_size=[num_envs])
evidence = initial_state_evidence(raw)
returns = torch.zeros(num_envs, device=exp.device)
lengths = torch.zeros(num_envs, device=exp.device)
episodes = torch.zeros(num_envs, device=exp.device, dtype=torch.long)
alive = torch.ones(num_envs, dtype=torch.bool, device=exp.device)
first_lengths = torch.zeros(num_envs, device=exp.device)
world_failures = torch.zeros_like(episodes)
first_failed = torch.zeros_like(alive)
completed_returns, completed_lengths = [], []
tracking_xy_sq = yaw_sq = reward_sum = 0.0
failures = timeouts = 0
if measure is not None:
from .measurement import JointRecorder
recorder = JointRecorder(measure, env)
if video is not None:
import imageio.v2 as imageio
video.parent.mkdir(parents=True, exist_ok=True)
writer = imageio.get_writer(str(video), fps=round(1 / raw.step_dt))
with torch.inference_mode():
for step in range(steps):
robot = raw.scene["robot"]
actual = robot.data.root_link_lin_vel_b[:, :2]
target = raw.command_manager.get_command("twist")
tracking_xy_sq += float((actual - target[:, :2]).square().sum().item())
yaw_sq += float(
(robot.data.root_link_ang_vel_b[:, 2] - target[:, 2]).square().sum().item()
)
actions = policy(obs)
if not torch.isfinite(actions).all():
raise FloatingPointError("Non-finite policy actions")
obs, rewards, done, _ = env.step(actions)
if not torch.isfinite(rewards).all() or any(
not torch.isfinite(value).all() for value in obs.values()
):
raise FloatingPointError("Non-finite evaluation state")
reward_sum += float(rewards.sum().item())
returns += rewards
lengths += 1
first_lengths += alive
terminated = raw.reset_terminated.clone()
# Disjoint categories: failure wins if timeout and failure happen together.
timeout = raw.reset_time_outs & ~terminated
first_failed |= alive & terminated
world_failures += terminated
failures += int(terminated.sum().item())
timeouts += int(timeout.sum().item())
ended = done.bool()
if recorder is not None:
recorder.record(
step, raw.step_dt, episodes, lengths, terminated, timeout, actions
)
if writer is not None:
frame = raw.render()
if frame is None:
raise RuntimeError("Renderer returned no frame")
writer.append_data(frame)
completed_returns.extend(returns[ended].tolist())
completed_lengths.extend(lengths[ended].tolist())
alive &= ~ended
episodes += ended
returns[ended] = 0
lengths[ended] = 0
if ended.any():
# Observe/record terminal states BEFORE resetting selected worlds.
observation, _ = raw.reset(env_ids=ended.nonzero(as_tuple=False).squeeze(-1))
obs = TensorDict(observation, batch_size=[num_envs])
count = steps * num_envs
dt = raw.step_dt
completed_count = len(completed_returns)
noise_terms = (
{
name: repr(term.noise)
for name, term in raw.cfg.observations["actor"].terms.items()
if term.noise is not None
}
if spec["actor_observation_noise"]
else {}
)
report = {
"schema_version": 2,
"status": "completed",
"created_at": now(),
"checkpoint": str(checkpoint.resolve()),
"checkpoint_sha256": digest(checkpoint),
"task": exp.task,
"experiment_sha256": run["experiment_sha256"],
"identity_sha256": run["provenance"]["identity_sha256"],
"training_seed": exp.seed,
"protocol": {
"name": "fixed-twist-v2",
"command": list(command),
"steps": steps,
"num_envs": num_envs,
"seed": evaluation_seed,
"step_dt": dt,
"episode_seconds": exp.episode_seconds,
"randomization": spec,
"actor_noise_terms": noise_terms,
"sampling": "tracking pre-step; joints post-step before manual reset",
},
"initial_states": evidence,
"per_world": {
"failure_events": world_failures.tolist(),
"completed_episodes": episodes.tolist(),
"first_episode_failed": first_failed.tolist(),
"first_episode_censored": alive.tolist(),
"push_events": (
raw.uh_push_counts.tolist()
if hasattr(raw, "uh_push_counts")
else [0] * num_envs
),
},
"metrics": {
"tracking_xy_rmse_m_s": (tracking_xy_sq / count) ** 0.5,
"tracking_yaw_rmse_rad_s": (yaw_sq / count) ** 0.5,
"mean_reward_per_step": reward_sum / count,
"failure_events": failures,
"timeout_events": timeouts,
"completed_episodes": completed_count,
"failure_fraction_completed": failures / completed_count
if completed_count
else None,
"failure_events_per_sim_second": failures / (count * dt),
"first_episode_failure_fraction": float(first_failed.float().mean().item()),
"mean_completed_return": sum(completed_returns) / completed_count
if completed_count
else None,
"mean_completed_seconds": sum(completed_lengths) * dt / completed_count
if completed_count
else None,
"mean_first_episode_observed_seconds": float(first_lengths.mean().item()) * dt,
"first_episode_censored_count": int(alive.sum().item()),
"unfinished_episode_count": int((lengths > 0).sum().item()),
},
"hardware_approved": False,
"note": (
"Evaluation seeds are not independent training runs. First-episode failure "
"fraction is bounded by the observed horizon; censored episodes are not successes."
),
}
if writer is not None:
writer.close()
writer = None
write_json(output, report)
completed = True
return report
finally:
if recorder is not None:
recorder.close(completed)
if writer is not None:
writer.close()
env.close()
def play(checkpoint: Path, viewer="native"):
from mjlab.viewer import NativeMujocoViewer, ViserPlayViewer
run = load_run(checkpoint, allow_incomplete=True)
exp = Experiment(**run["experiment"]).validate()
env, agent_cfg = make_env(exp, evaluation=True, num_envs=1)
try:
runner = make_runner(env, agent_cfg)
runner.load(str(checkpoint), load_cfg={"actor": True}, map_location=exp.device)
policy = runner.get_inference_policy(device=exp.device)
viewer_cls = NativeMujocoViewer if viewer == "native" else ViserPlayViewer
viewer_cls(env, policy).run()
finally:
env.close()
+79
View File
@@ -0,0 +1,79 @@
"""The sole adapter boundary between experiment data and mjlab task factories."""
import copy
import inspect
from .config import Experiment
from .registry import get_task, resolve_factory
def build_configs(
exp: Experiment, *, evaluation=False, num_envs=None, command=None, profile="nominal"
):
from .backend import require_vendored
require_vendored()
from mjlab.managers.reward_manager import RewardTermCfg
from .rewards import FUNCTIONS
exp.validate()
task = get_task(exp.task)
# Deep copy also isolates mutable nested objects returned by upstream factories.
env = copy.deepcopy(resolve_factory(task.env_factory)(play=False))
agent = copy.deepcopy(resolve_factory(task.rl_factory)())
env.scene.num_envs = num_envs if num_envs is not None else exp.num_envs
env.seed = agent.seed = exp.seed
env.episode_length_s = exp.episode_seconds
agent.max_iterations = exp.iterations
agent.num_steps_per_env = exp.steps_per_env
agent.clip_actions = exp.action_clip
agent.logger = "tensorboard"
agent.upload_model = False
agent.experiment_name = exp.task
agent.save_interval = min(exp.checkpoint_interval, exp.iterations)
for name, value in exp.extra_rewards.items():
if name in env.rewards:
raise ValueError(f"Extra reward shadows built-in reward: {name}")
function_name = value["function"]
if function_name not in FUNCTIONS:
raise ValueError(f"Unknown local reward function: {function_name}")
params = value.get("params", {})
inspect.signature(FUNCTIONS[function_name]).bind(None, **params)
env.rewards[name] = RewardTermCfg(
func=FUNCTIONS[function_name], weight=value["weight"], params=dict(params)
)
for name, weight in exp.reward_weights.items():
if name not in env.rewards:
raise ValueError(f"Unknown reward weight: {name}")
env.rewards[name].weight = weight
for name, params in exp.reward_params.items():
if name not in env.rewards:
raise ValueError(f"Unknown reward parameters: {name}")
unknown = set(params) - set(env.rewards[name].params)
if unknown:
raise ValueError(f"Unknown parameters for {name}: {sorted(unknown)}")
# Structured SceneEntityCfg values must not be replaced with untyped dictionaries.
for key, value in params.items():
old = env.rewards[name].params[key]
if hasattr(old, "__dataclass_fields__"):
raise ValueError(f"Edit the adapter for structured parameter {name}.{key}")
env.rewards[name].params[key] = copy.deepcopy(value)
if evaluation:
# Do not use upstream play=True: it silently makes episodes effectively infinite.
env.curriculum = {}
from .evaluation import configure_evaluation
configure_evaluation(env, profile)
twist = env.commands["twist"]
twist.heading_command = False
twist.ranges.heading = None
twist.rel_heading_envs = 0.0
twist.rel_forward_envs = 0.0
twist.rel_standing_envs = 0.0
if command is not None:
vx, vy, wz = command
twist.ranges.lin_vel_x = (vx, vx)
twist.ranges.lin_vel_y = (vy, vy)
twist.ranges.ang_vel_z = (wz, wz)
return env, agent
+216
View File
@@ -0,0 +1,216 @@
"""Atomic intermediate checkpoints, optimizer resume and iteration-level progress."""
import os
import time
from dataclasses import asdict
from pathlib import Path
from .artifacts import (
canonical_hash,
digest,
load_run,
now,
provenance,
snapshot_sources,
write_json,
)
from .config import Experiment
def resume_experiment(checkpoint, iterations):
run = load_run(checkpoint, allow_incomplete=True)
exp = Experiment(**run["experiment"])
exp.iterations = iterations
return exp.validate()
def checkpoint_listing(directory):
from .artifacts import read_json
run = read_json(directory / "run.json")
rows = []
for name, sha in run["checkpoints"].items():
path = directory / name
if Path(name).name != name:
raise ValueError("Invalid checkpoint filename in manifest")
meta = run.get("checkpoint_metadata", {}).get(name, {})
rows.append(
{
"path": str(path),
"sha256": sha,
**meta,
"integrity": path.is_file() and digest(path) == sha,
}
)
return {"status": run["status"], "checkpoints": rows}
class ProgressLogger:
"""Instance-local observer; delegates logging without changing upstream code."""
def __init__(self, logger, callback):
self.inner = logger
self.callback = callback
def __getattr__(self, name):
return getattr(self.inner, name)
def log(self, **kwargs):
self.inner.log(**kwargs)
# Make scalar queries useful during training, not just after writer close.
if self.inner.writer is not None:
self.inner.writer.flush()
self.callback(kwargs)
def training_runner(env, agent_cfg, output, run, progress):
from mjlab.rl import MjlabOnPolicyRunner
class RecordedRunner(MjlabOnPolicyRunner):
def save(self, path, infos=None):
destination = Path(path)
completed = self.current_learning_iteration + 1
# Upstream saves the last periodic checkpoint twice. Keep published files immutable.
if destination.name in run["checkpoints"]:
if (
run["checkpoint_metadata"][destination.name]["completed_iterations"]
!= completed
):
raise ValueError("Refusing to overwrite a published checkpoint")
return
temporary = destination.with_suffix(f".pt.{os.getpid()}.tmp")
metadata = {"completed_iterations": completed, "committed": True, "saved_at": now()}
super().save(str(temporary), {**(infos or {}), "universal_humanoid": metadata})
temporary.replace(destination)
run["checkpoints"][destination.name] = digest(destination)
run["checkpoint_metadata"][destination.name] = metadata
write_json(output / "run.json", run)
progress["latest_checkpoint"] = str(destination)
progress["updated_at"] = now()
write_json(output / "progress.json", progress)
return RecordedRunner(env, asdict(agent_cfg), str(output), env.unwrapped.device)
def train(exp: Experiment, output: Path, *, resume: Path | None = None):
from mjlab.utils.os import dump_yaml
from .jobs import process_identity
from .runtime import make_env
exp.validate()
parent = None
if resume is not None:
resume = resume.resolve(strict=True)
parent = load_run(resume, allow_incomplete=True)
expected = Experiment(**parent["experiment"]).to_dict()
actual = exp.to_dict()
for key in ("iterations", "checkpoint_interval"):
expected.pop(key)
actual.pop(key)
if expected != actual:
raise ValueError(
"Resume may change iterations/checkpoint_interval only; "
"start a new experiment otherwise"
)
if resume.name not in parent.get("checkpoint_metadata", {}):
raise ValueError("Resume requires a checkpoint with recorded completed_iterations")
output.mkdir(parents=True, exist_ok=False)
run = {
"schema_version": 2,
"status": "initializing",
"started_at": now(),
"experiment": exp.to_dict(),
"experiment_sha256": canonical_hash(exp.to_dict()),
"checkpoints": {},
"checkpoint_metadata": {},
"hardware_approved": False,
"process_identity": process_identity(os.getpid()),
}
progress = {
"status": "initializing",
"updated_at": now(),
"completed_iterations": 0,
"additional_iterations": exp.iterations,
"latest_checkpoint": None,
}
write_json(output / "run.json", run)
write_json(output / "progress.json", progress)
write_json(output / "experiment.json", exp.to_dict())
env = runner = None
started = time.monotonic()
try:
run["provenance"] = provenance(exp.task)
run["source_archive_sha256"] = snapshot_sources(output, run["provenance"])
env, agent_cfg = make_env(exp)
dump_yaml(output / "resolved_env.yaml", asdict(env.unwrapped.cfg))
write_json(output / "resolved_agent.json", asdict(agent_cfg))
runner = training_runner(env, agent_cfg, output, run, progress)
start_iteration = 0
if parent:
runner.load(
str(resume), map_location=exp.device
) # actor, critic, optimizer, normalizers
start_iteration = parent["checkpoint_metadata"][resume.name]["completed_iterations"]
# Upstream 'iter' is a zero-based LAST update, not the NEXT update.
runner.current_learning_iteration = start_iteration
run["resume"] = {
"checkpoint": str(resume),
"sha256": digest(resume),
"parent_experiment_sha256": parent["experiment_sha256"],
"start_iteration": start_iteration,
"semantics": (
"optimizer continuation; simulator/RNG/rollout state restarts, "
"not bitwise replay"
),
}
target = start_iteration + exp.iterations
progress.update(
status="training",
completed_iterations=start_iteration,
start_iteration=start_iteration,
target_iterations=target,
)
run["status"] = "training"
write_json(output / "run.json", run)
write_json(output / "progress.json", progress)
def update(values):
completed = values["it"] + 1
elapsed = time.monotonic() - started
session_completed = completed - start_iteration
progress.update(
status="training",
updated_at=now(),
completed_iterations=completed,
session_env_steps=session_completed * exp.num_envs * exp.steps_per_env,
elapsed_seconds=elapsed,
eta_seconds=elapsed / session_completed * (target - completed),
iteration_seconds=values["collect_time"] + values["learn_time"],
learning_rate=float(values["learning_rate"]),
mean_action_std=float(values["action_std"].mean().item()),
losses={key: float(value) for key, value in values["loss_dict"].items()},
)
write_json(output / "progress.json", progress)
runner.logger = ProgressLogger(runner.logger, update)
runner.learn(num_learning_iterations=exp.iterations, init_at_random_ep_len=True)
runner.save(str(output / "final.pt"))
run["status"] = "completed"
except BaseException as error:
run["status"] = "interrupted" if isinstance(error, KeyboardInterrupt) else "failed"
run["error"] = f"{type(error).__name__}: {error}"
raise
finally:
run["finished_at"] = now()
progress.update(
status=run["status"], updated_at=now(), elapsed_seconds=time.monotonic() - started
)
write_json(output / "run.json", run)
write_json(output / "progress.json", progress)
if runner is not None and runner.logger.writer is not None:
runner.logger.writer.flush()
runner.logger.writer.close()
if env is not None:
env.close()
return output / "final.pt"
+43
View File
@@ -0,0 +1,43 @@
"""Internal detached training entry point; not a remote execution service."""
import signal
import sys
from pathlib import Path
from .artifacts import now, read_json, write_json
from .config import Experiment
def main():
job = Path(sys.argv[1])
def interrupt(signum, frame):
raise KeyboardInterrupt(f"signal {signum}")
signal.signal(signal.SIGTERM, interrupt)
signal.signal(signal.SIGINT, interrupt)
state = {"status": "running", "updated_at": now()}
write_json(job / "state.json", state)
try:
from .training import train
spec = read_json(job / "spec.json")
checkpoint = train(
Experiment(**spec["experiment"]).validate(),
Path(spec["output"]),
resume=Path(spec["resume"]) if spec["resume"] else None,
)
state.update(status="completed", checkpoint=str(checkpoint))
except BaseException as error:
state.update(
status="interrupted" if isinstance(error, KeyboardInterrupt) else "failed",
error=f"{type(error).__name__}: {error}",
)
raise
finally:
state["updated_at"] = now()
write_json(job / "state.json", state)
if __name__ == "__main__":
main()