Files
UniversalTrain-ai/docs/USAGE.md
T
chenlin d5e9004f6c
Checks / Layout, translation and Colab checks (push) Has been cancelled
Checks / Ruff (push) Has been cancelled
Checks / Framework tests (native backend, CPU) (push) Has been cancelled
Checks / Portable Rust controller (push) Has been cancelled
docs: add AI agent workflow guide and clean up residual single-robot references
2026-11-05 11:52:07 +08:00

11 KiB
Raw Blame History

Command reference

Install this checkout in a Python 3.10–3.13 environment with python -m pip install -e ".[dev]". See Agent setup for platform-specific setup. The editable install connects both package roots.

Onboard

python scripts/onboard.py --help
python scripts/onboard.py inspect <model-or-directory> --profile <profile.json>
python scripts/onboard.py build-mjcf <model-mesh-or-directory> --output <robot.xml>
python scripts/onboard.py extract-tier1 env.yaml agent.yaml --model <robot.xml> --output <metadata-dir>
python scripts/onboard.py adapt-tier1 <actor.onnx> --metadata <metadata.json> --model <robot.xml> --output <policy-dir>
python scripts/onboard.py adapt-tier1 <actor.onnx> --config env.yaml --config agent.yaml --overrides reviewed.json --model <robot.xml> --output <policy-dir>
python scripts/onboard.py setup-tier2 --model <robot.xml> --config <controller.json> --output <control-dir>
python scripts/onboard.py calibrate --model <robot.xml> --config <stance.json> --report <calibration.json>
python scripts/onboard.py verify --model <robot.xml> --config <probe.json> --report <verification.json>
python scripts/onboard.py scaffold-tier3 --config <robot.json> --calibration <calibration.json>

Each subcommand has its own --help. inspect accepts optional --policy, --metadata, and --mesh-root. In an asset directory, build-mjcf searches recursively for one URDF or MJCF, or one STL, OBJ, or MSH when there is no model. Pass a file explicitly when the directory has several candidates at the selected level. The requested output path is excluded from the search. --floating-base adds a free URDF root, --mesh-root extends URDF asset search, --mesh-scale scales standalone meshes, and --visual-fallback opts into approximate URDF collision geometry. Choose fresh report and output paths unless the command explicitly allows replacement. Calibration and verification emit JSON and return a failing status when the requested checks fail.

extract-tier1 reads selected YAML, JSON or static Python training configs. Use --overrides to supply reviewed JSON or YAML values and --report for a separate extraction report. The output directory contains metadata.json and manifest.json, including on an incomplete extraction with exit status

  1. Review the provenance and unresolved fields. Adapt from a manifest with ready: true, or supply the same reviewed inputs through repeated --config arguments in place of --metadata. See the Tier 1 walkthrough.

Python API

from mjrl.onboarding import build_mjcf, calibrate_model, inspect_asset, scaffold_task, verify_model

intake = inspect_asset(source, profile=profile)
build = build_mjcf(source, model_path)
calibration = calibrate_model(model_path, stance_config)
verification = verify_model(model_path, probe_config, base_dir=config_directory)
registration = scaffold_task(robot_config, base_dir=config_directory, calibration=calibration)

These functions return report dictionaries. The profiles and configs are Python mappings. base_dir resolves relative verification configuration paths and defaults to the model's directory for verification. Scaffolding requires base_dir for relative model and controls paths. Supply tasks_root to write the specification into a different task directory.

Use mjrl.onboarding.extract_policy_metadata for programmatic Tier 1 metadata extraction and readiness diagnostics. Pass a sequence of config paths and, if available, the compiled MuJoCo model and a mapping of reviewed overrides.

from mjrl.onboarding import extract_policy_metadata

extraction = extract_policy_metadata(
    [env_config_path, agent_config_path], overrides=reviewed, model=compiled_model
)

The result contains the canonical draft under metadata and the readiness and provenance fields written by the CLI.

Robot specification

The calibrated scaffold config names robot_id, family, model_path, and action_scales keyed by calibrated position-joint name. It can also name controls_path, velocity_joints, penalized_contact_geoms, and termination_contact_geoms. Model and controls paths resolve relative to the input JSON. The calibration must match the model XML and compiled dependencies.

Without --calibration, give a full RobotSpec from verified model facts. This example shows the file shape:

{
  "robot_id": "sample_biped",
  "family": "biped",
  "model_path": "assets/sample_biped/robot.xml",
  "base_body": "base",
  "base_height": 0.32,
  "foot_geoms": ["left_foot", "right_foot"],
  "penalized_contact_geoms": ["left_shin", "right_shin"],
  "termination_contact_geoms": ["torso"],
  "position_joints": [
    {"name": "left_hip", "kp": 20, "kd": 1, "effort_limit": 8, "action_scale": 0.25, "home": 0.1},
    {"name": "right_hip", "kp": 20, "kd": 1, "effort_limit": 8, "action_scale": 0.25, "home": 0.1}
  ]
}

Use calibrated values for the robot. base_height is its standing root height. Each joint's home supplies its default joint position. Optional armature is additional inertia at that joint. Supply either foot_geoms or foot_bodies. Each named foot body needs named collision geoms directly on it. The minimum support counts are two for biped and wheeled biped, four for quadruped, and five for multipod. A wheeled biped also needs at least two named unlimited wheel hinges in velocity_joints, with kp: 0, positive kd, an effort limit, and a velocity action scale.

Scaffolding writes only tasks/<robot_id>/robot_spec.py in the task tree. The robot ID is the task ID. Family values are biped, quadruped, wheeled_biped, and multipod. The controls file for a locomotion policy uses the body-frame twist term feeding velocity_commands, with lin_vel_x, lin_vel_y, and ang_vel_z in that order. For operator input, generate the bindings before scaffolding and set controls_path in the input JSON. Choose --profile differential for a wheeled biped to use A/D for yaw.

Train and replay

python scripts/train.py --list
python scripts/train.py --task <robot_id> --dry-run
python scripts/train.py --task <robot_id> --backend native --device cpu --num_envs 64 --headless
python scripts/train.py --task <robot_id> --resume --max-iterations 100
python scripts/play.py --task <robot_id> --checkpoint <model_N.pt> --headless --steps 300 --speed 0 --measure

Use --backend warp --device cuda for the GPU path. Explicit requests fail when their device is unavailable. Native starts at 64 parallel environments and Warp at 4096 when no count is set. Start with fewer for an execution smoke or an asset with high memory use.

Warp constraint and contact capacities can be set with positive integers using --warp-max-constraints N and --warp-max-contacts N. Constraints are capped per world. Contacts share a pool sized from the per-world setting and the environment count. A Warp buffer overflow stops the run before it uses the affected observations. For example, the G1 flat setup uses --warp-max-constraints 300.

A Warp run saves selected and effective capacities in warp-allocation.json beside its checkpoints. Warp resume, replay, and export read this file when present. Explicit flags take precedence. Otherwise, the larger of the saved capacity and the task or scene requirement is used. Without a run record or a configured capacity, Warp chooses the size.

Training logs to logs/<model>/<robot_id>/<timestamp>/. The default --logger is tensorboard. Use --no-tensorboard to skip starting its server. --max-iterations caps this invocation. --resume selects the latest checkpoint and --checkpoint selects a particular one. Both restore the optimizer, iteration, and curriculum state. On resume, --max-iterations is the number of additional iterations.

Replay retains actor observation noise by default. Use --no-obs-noise for a clean comparison. --checkpoint-command-ranges restores the checkpoint's command curriculum ranges. To evaluate a fixed body command, use --command VX VY YAW --evaluation-out <metrics.json> with a trained checkpoint and positive --steps. --measure records joint signals. Use --physics-hz only when deliberately evaluating a different integration rate. The default task simulation rate comes from its template. Built-in scenes work in training and replay. Imported .map scenes are replay-only.

Rough terrain uses explicit nominal dimensions, not a hidden robot model: --terrain-robot-height 0.25, --terrain-stance 0.40, and --terrain-foot-lift 0.04 (metres). With --scene rough, set these to the calibrated asset's dimensions when comparing terrain difficulty. Height and stance scale vertical and horizontal obstacles independently; foot lift sets continuous roughness. The Python scene arguments are robot_height, stance, and foot_lift. All must be finite and positive.

Export and package

python scripts/export.py --task <robot_id> --checkpoint <model_N.pt> --out <policy-dir>
python scripts/deploy.py --robot <robot_id> --model <robot.xml> --bundle <output-parent>
python scripts/play.py --app <output-parent>/<robot_id>.app --headless --steps 100

Export writes the actor, its layout, a checkpoint copy, and a README. It checks observation and action dimensions, home pose, and ONNX parity. Add --native-layout to export a replay-ready native model and controller next to the policy. Hybrid position and velocity actions automatically use the native layout. Legacy Rust consumers accept their position-action layout. See Controller setup.

A model-only build creates a viewer app. A controlled native build includes --control <controller.json>, --verification <verification.json>, and --controls <controls.yaml> when the report verified operator bindings. For a compatible ONNX mode, also pass --policy <policy-dir>. For multiple modes, use --platform-manifest <manifest.json>. See the bundle format for mode fields and runtime requirements. The legacy target flags build the separate Rust bundle format.

Defaults

Precedence is command line, shell environment, .env.local, .env, then the argument default. Copy .env.example to .env to set local defaults. A blank task means a task is required on task entry points. A blank model selects the robot's registered model. The effective defaults are:

MJRL_TASK=
MJRL_MODEL=
MJRL_SCENE=
MJRL_TERRAIN_ROW=
MJRL_TERRAIN_COL=
MJRL_BACKEND=auto
MJRL_DEVICE=auto
MJRL_NUM_ENVS=
MJRL_PLAY_NUM_ENVS=1
MJRL_CPU_THREADS=0
MJRL_STRIP_VISUAL=auto
MJRL_TENSORBOARD=on
MJRL_TB_PORT=6006

The terrain row and column select one rough-terrain tile when set. Native MJRL_CPU_THREADS=0 selects threads automatically. Native visual stripping can reduce per-environment memory and affects camera sensor appearance. TensorBoard binds to localhost and skips occupied ports.