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
+102
View File
@@ -0,0 +1,102 @@
# Architecture and extension seams
## Layers
```text
Coding agent / operator
AGENTS.md + rl-engineer playbook
|
Unified CLI (no robot-specific branches)
strict experiment JSON, bounded commands, durable run/pipeline status
|
Metadata registry → lazy task factory → config adapter
robot facts mjlab baseline reward overrides / evaluation protocol
|
mjlab ManagerBasedRlEnv
observation | action | command | reward | termination | event | curriculum
|
MuJoCo Warp (CUDA) → RSL-RL PPO
|
checkpoint + source/asset identity
|
fixed-command evaluation + video → ONNX parity → research bundle
```
## Relationship to Jumper
Reuse the architectural principles: independent task modules, centralized commands, explicit
agent playbooks, and a deployment contract resolved from the actual environment. Do not copy
its hexapod control assumptions, native backend patches, RKNN conversion or Rust FSM. This
project uses the existing mjlab `Simulation` and manager API without monkey-patching it. Native
MuJoCo is used only to inspect MJCF and by the optional viewer, not as a hidden RL fallback.
## Backend and adapter contract
Registry entries reference environment, training and asset factories through importable Python
paths. A compatible backend must provide those interfaces; the registry does not download or
convert missing adapters. Fingerprints include **all Python files**, not merely git HEAD.
The validated mjlab 1.6.0 source, its two inherited runtime patches, T1 extension and RSL-RL 5.5.1
are now vendored under `rl/`, installed as top-level packages with the project. Runtime guards
reject an external shadowing backend. `uv.lock` fixes transitive dependencies; `rl/VENDOR.json`
checks source and asset inventory. See [Vendor provenance](VENDOR.md) and [Setup](SETUP.md).
G1 and T1 use bundled adapted models with original asset licenses. `BOOSTER_ASSETS_ROOT` is an
optional explicit T1 override, not a hidden HOME default. Raw Unitree ROS XML can be inspected
but is not mechanically or semantically interchangeable with those models. `check-robot` checks
resolved interfaces against independent declarations in `robot_specs/`, then measures short
contact/PD response. See [Robot checks](NEW_ROBOT.md).
## Add a robot/task without changing the CLI
1. Provide a robot `EntityCfg` factory: MJCF `spec_fn`, PD/motor definitions, initial posture,
collision rules, foot sites and required sensors. Do not infer motor ratings from joint names.
2. Provide an environment factory `factory(play=False)` returning an independent config and an
RSL-RL config factory. The initial contract is a flat velocity task: entity `robot`, command
`twist`, `joint_pos` position action, actor/critic observation groups, reset events.
3. Add metadata in `registry.py`: ID, robot, expected action DoF, lazy factory paths, asset
reference (Path or callable returning Path), and number of parent levels covering its assets.
4. Add an experiment. No train/evaluate/export command needs robot-specific changes.
5. Validate all task seams with the playbook. The current exporter deliberately requires one
built-in position actuator per controlled joint. Tendons, coupled drives, recurrent networks,
multiple action groups and history stacks need an explicitly versioned contract extension.
Task registry extensibility is not automatic adaptation to arbitrary morphology. A future
tracking/manipulation task needs a separate task protocol rather than abusing the twist interface.
## Reproducibility and evaluation
Runs contain the input experiment, resolved environment/agent configuration, checkpoint hashes,
Python/config source archive, both backend source identities, dependency lock/versions and
source/asset fingerprints. Bundled and optional external model assets retain their original
licenses; meshes are not copied into training source archives. Replay/export refuse changed source/assets/runtime
versions. Archives are for manual trusted restoration, never automatic execution.
Comparison intentionally permits different reward/source hashes but requires the same task and
evaluation protocol. Inspect provenance to ensure differences really are reward-only; the CLI does
not prove scientific causal isolation. Use multiple seeds, more than one command and adequate
horizons. `status=completed` means the operation finished, not the policy passed a quality gate.
## Resource and trust model
No remote shell, multi-agent scheduler, cloud logger or motor transport is started. Training is
bounded by the experiment's iterations. `train --background` optionally launches a detached local
Linux worker with progress, logs and PID-guarded stop; foreground execution remains the default.
`pipeline` records the current stage and failure. Graceful interruption records `interrupted`;
SIGKILL/power loss can leave stale status, which `status` reports as lost when the recorded process
is dead. Never rewrite a failed/interrupted run to completed.
`training.py` atomically publishes intermediate checkpoints, records completed-update counts and
observes the backend logger without editing external packages. `jobs.py` / `worker.py` manage
local process lifecycle; `curves.py` reads scalar logs without a server. `evaluation.py` defines
versioned randomized/stress profiles; `benchmark.py` aggregates seed-level reports and selects
explicit candidates. `measurement.py` records terminal joint states before manual reset.
Evaluation/resume may explicitly load a committed checkpoint from an incomplete run after
checking its hash and provenance. Export still requires a completed run. Resume uses a new output
branch and restores optimizer/model/curriculum-counter state, not simulator or RNG trajectories.
See [Training operations](TRAINING_OPERATIONS.md) for the statistical and lifecycle contracts.
Hash manifests are integrity evidence, not cryptographic signatures. Checkpoints and Python task
factories are executable trusted inputs. Source paths and git status are recorded; `.env` and
credentials are not copied. Binary policies cannot establish physical safety.
+46
View File
@@ -0,0 +1,46 @@
# CLI reference
Run `./scripts/uh COMMAND --help` or the installed `uh COMMAND --help`. All paths are explicit;
run/output directories must be new where the command creates an artifact. This table lists every
public command and its named options (excluding automatic `--help`). Layout tests compare it to
the actual argparse parser; change the table with the interface.
| Command | Named options | Purpose / positional inputs |
|---|---|---|
| `list` | — | Registered task metadata |
| `doctor` | — | Installed backend, locked core versions and CUDA |
| `verify-vendor` | — | Checked-in source/asset inventory |
| `check-robot` | `--config --output --steps --spec` | Robot interface/mechanics/contact gate |
| `assets` | — | Discover explicitly configured optional external assets |
| `inspect-asset` | — | Native MJCF compile; positional model path |
| `plan` | `--config` | Resolve experiment metadata without simulation |
| `rewards` | `--config` | Resolve reward functions/weights/parameters |
| `smoke` | `--config --steps --num-envs` | Bounded zero-action GPU probe |
| `train` | `--config --resume --iterations --background --output` | PPO or additional updates from a committed checkpoint |
| `pipeline` | `--config --output --eval-steps --eval-envs` | Bounded train/evaluate/export sequence |
| `evaluate` | `--checkpoint --output --steps --num-envs --command --video --seed --profile --measure` | Fixed-command evaluation with optional measurement/video |
| `play` | `--checkpoint --viewer --measure --steps --seed --profile --command --video` | Interactive viewer, or bounded headless measured replay |
| `status` | — | Positional run directory; progress and process state |
| `stop` | — | Positional background run directory; guarded graceful stop |
| `checkpoints` | — | Positional run directory; committed checkpoint inventory |
| `curves` | `--output --match --window` | Positional run directory; TensorBoard JSON/CSV/SVG |
| `benchmark` | `--checkpoints --output --seeds --profiles --steps --num-envs` | Checkpoint × evaluation-seed × command × profile matrix |
| `select-checkpoint` | `--output --metric` | Positional completed matrix summary; explicit-metric ranking |
| `export` | `--checkpoint --evaluation --output` | Research-only ONNX bundle |
| `verify-bundle` | `--inference` | Positional bundle; integrity and optional inference parity |
| `compare` | — | Positional baseline/candidate reports or single-checkpoint matrix summaries |
## Important semantics
- `doctor`, `verify-vendor` and `check-robot` failures give a nonzero exit. A failed robot gate
writes its JSON report; a model construction failure cannot provide downstream dynamic checks.
- `--iterations` on resume is additional updates; it is not the target total update index.
- `benchmark --seeds` sets evaluation randomness, not independent training runs.
- `play --measure` selects bounded headless replay. Its seed/profile/command/steps/video options
describe that mode; ordinary `play --viewer` is the interactive viewer path.
- Default evaluation profile is randomized; stress adds configured observation noise and velocity
kicks. Nominal fixed replicas do not become independent samples merely by increasing worlds.
- Backend diagnostics may accompany JSON on stdout. Read generated JSON artifacts for automation.
References: [Setup](SETUP.md), [Robot checks](NEW_ROBOT.md), [Training operations](TRAINING_OPERATIONS.md),
[Bundle contract](DEPLOYMENT.md). Hardware approval is not a CLI operation.
+61
View File
@@ -0,0 +1,61 @@
# Research bundle schema v1
An export is an immutable directory:
```text
policy.onnx deterministic actor, with trained observation normalization
contract.json observation/action ordering, affine transforms, simulation PD settings
reference.json one raw observation and its expected unclipped policy action
evaluation.json fixed-protocol rollout evidence bound to the checkpoint/source hashes
experiment.json original experiment
agent.json runner architecture/configuration
provenance.json source/assets/runtime versions and hashes
manifest.json SHA-256 of every payload file, checkpoint hash, ONNX parity results
```
The bundle contains no robot meshes, checkpoint pickle, board executable or motor transport.
It is portable for **CPU ONNX inference**, not a self-contained simulation environment. Replay
still needs the recorded task code, asset checkout and compatible mjlab environment.
## Consumer contract
`PolicyRuntime(Path(bundle)).predict(observation)` accepts a finite float32 `[1, observation_size]`
array. Observation terms must be concatenated in the exact `start:stop` order. Read each term's
function identity in `contract.json`; implementation semantics are in the recorded sources.
For current flat tasks, terms are base linear/angular velocity from the configured IMU sensors,
projected gravity, joint position relative to default, joint velocity relative to default,
previous clipped raw action, and `(vx, vy, yaw_rate)` commands. Sensor frame/site and filtering
matter; a base estimator cannot be substituted without validating parity. Joint observation
ordering is explicitly separate from action ordering. Units are SI; angles in radians.
Normalization is inside ONNX. Do **not** normalize twice. On reset, previous action is zero.
During inference:
```text
raw_action = policy(observation)
clipped_action = clip(raw_action, -raw_clip, raw_clip)
joint_target_rad = offset + scale * clipped_action
```
The consumer returns all three arrays and does not send them anywhere. Host PD/control frequency
must match the recorded policy/physics timestep semantics. Simulation gain and torque data are
metadata, not a certified motor configuration. Joint-limit clamping is not silently added to
inference because it would change training semantics; a physical safety controller must be
separately designed, validated and may refuse the policy.
## Export checks and limits
Export requires a completed local run and matching evaluation report. It tests ONNX checker
validity and action parity at 16 actual rollout observations (`atol=1e-5`, `rtol=1e-4`), then
writes file hashes. `verify-bundle --inference` checks integrity and one saved reference.
This detects common swapped-joint/normalizer/version mistakes, but is not a complete behavioral
proof. The current exporter requires MLP, one joint-position action group, no per-joint action
clip, one position actuator per joint and batch size one. It does not generate a robot driver.
A report can show poor tracking and many falls and still be packaged for research. All bundles
are `hardware_approved: false`. There is no release-quality gate or hardware approval command.
Before physical deployment, implement and validate bus index mapping, estimator/calibration,
IMU frame, latency, torque/position bounds, thermal limits, watchdog, controlled startup/shutdown,
E-stop and supervised sim-to-real tests. Require explicit operator authorization for actual motion.
+72
View File
@@ -0,0 +1,72 @@
# Adding and checking a robot/task
Asset compilation is only the first step. A robot adapter must explicitly define model mechanics,
sensors, controls, observations, reset posture and task semantics. There is no automatic
conversion of an arbitrary MJCF into a validated walking task.
## One-command conformance check
```bash
./scripts/uh check-robot --config experiments/g1_smoke.json --output runs/g1-check.json
./scripts/uh check-robot --config experiments/t1_smoke.json --output runs/t1-check.json
```
The command builds the **actual nominal task**, then performs a bounded zero-action PD probe
(default 32 control steps, one CUDA world). No policy or hardware is loaded. It produces JSON
and exits nonzero if any check fails. The report contains these stable check IDs:
| Check ID | What is actually checked |
|---|---|
| `free_root` | Exactly one floating root joint |
| `foot_sites` | Named foot sites exist on declared bodies, with declared local positions/orientations and plausible initial height above flat ground |
| `imu` | Declared sensor names, types and dimensions; exact reference site, parent body, local position and orientation |
| `joint_order` | Resolved action joint order and observation joint order match the separately declared lists; no duplicate action names |
| `pd_and_limits` | One joint-transmission actuator per controlled hinge; enabled torque/joint limits, finite positive stiffness/nonnegative damping, expected gains, gear and ranges |
| `action_transform` | Resolved action scales/offsets and physics/policy timestep match the declaration |
| `initial_pose` | Default and actual root/joint pose, nominal +0.02 m reset height, zero initial velocities, hard-limit compliance and upright orientation |
| `initial_penetration` | Native MuJoCo contact distance at the initialized task pose stays within the declared penetration threshold |
| `contact_configuration` | Contact sensor resolves the declared foot bodies, filters terrain, requests found/force fields and has enabled collision geometry |
| `contact_response` | Each declared foot actually reports contact and positive force during the probe |
| `finite_probe` | Observations/rewards/joints/torques/contact forces stay finite, with no task termination during the bounded probe |
Foot force magnitude, initial local site placement, gains, limits, names and timing are retained
as evidence. A construction failure is reported rather than converted into a pass; checks that
require a successfully constructed environment cannot run after construction fails.
This checks interface consistency and a short contact/control response—not motor identification,
long-term balance, mesh realism, convergence, force accuracy or hardware safety. Initial penetration
uses native MuJoCo on the compiled model; runtime contacts use the actual Warp task. These are
complementary checks, not claims of bitwise physics parity.
## Adapter procedure
1. **Inspect assets and licensing.** Use `inspect-asset PATH`. Confirm mesh references, floating
root, units, mass/inertia, hinges, limits, actuator transmissions and model variant. Keep new
adapters in this project's package; do not silently edit a shared external repository.
2. **Define robot mechanics.** Implement an `EntityCfg` factory, explicit PD/effort settings,
reset pose, collisions, foot sites and IMU sensors. Record the source of hardware facts.
3. **Define the task.** Provide independent environment/PPO factories following
[ARCHITECTURE.md](ARCHITECTURE.md). Existing flat-velocity integration expects entity `robot`,
command `twist`, `joint_pos` actions, actor/critic groups, and base/joint reset events.
4. **Register metadata.** Add a `Task` in `src/universal_humanoid/registry.py` and a bounded
experiment in `experiments/`. The CLI itself should not gain robot-specific branches.
5. **Declare independent expectations.** Add `src/universal_humanoid/robot_specs/<robot>.json`,
using an existing declaration as a schema example. Review every joint order, gain, limit,
site, IMU frame and posture against intended mechanics. Do not auto-generate expected values
from the very environment being checked—that would validate a mistake against itself.
6. **Run the gate.** Use `check-robot --config ... --output NEW.json`. During development an
explicit `--spec FILE.json` can be used; it must match the task and schema. Unknown/missing
sites, changed PD gains, swapped order or absent contact must remain failures.
7. **Test behavior.** Add unit/negative tests, then bounded PPO, randomized/stress evaluation,
measured CSV/video replay and ONNX parity. A passing robot gate is not the final acceptance.
The supplied declarations encode the existing adapted G1 and T1 baselines; they are **simulation
contracts**, not certified hardware specifications. Updating an intended control setting requires
review of both the adapter and declaration, followed by new tests and run provenance.
## Nonstandard robots/tasks
This checker and exporter intentionally target flat-ground humanoids with one position actuator
per controlled hinge. Tendons, coupled actuators, prismatic joints, multiple action groups,
non-flat terrain or non-velocity tasks need an explicit extension of the contract and tests.
Do not relax a check until it passes while continuing to claim the old contract.
+102
View File
@@ -0,0 +1,102 @@
# Training-operations validation
Reference-environment checks on **2026-11-03**, using the Linux/RTX 5080 backend described in
[VALIDATION.md](VALIDATION.md). The files below are development evidence under ignored `runs/`,
not artifacts shipped with a fresh repository clone. Usage and statistical definitions are in
[TRAINING_OPERATIONS.md](TRAINING_OPERATIONS.md).
## Automated checks
**58 tests passed**; Ruff lint/format passed. One upstream TorchScript deprecation warning remains.
New checks cover seed-level sample variance and null statistics, duplicate/mismatched protocols,
paired comparisons, selection coverage, TensorBoard scalar reading and `/time` axis handling,
CSV joint ordering and projected torque, atomic checkpoint publication and update indexing,
committed-vs-uncommitted partial runs, Linux PID identity/stop, and both robots' evaluation profiles.
## Background training and real interruption/resume
- `runs/ops_g1_validation`: 16 environments × 24 steps × **4 updates**, launched with
`train --background`; state progressed to completed, with live progress and committed
`model_0.pt`, `model_3.pt`, `final.pt` visible through the CLI.
- `runs/ops_interrupt_validation`: a bounded 16-update job was deliberately stopped after its
first committed checkpoint. `status` observed it alive/training; `stop` sent SIGTERM;
worker and run both recorded **interrupted**, preserving `model_0.pt`.
- `runs/ops_resume_validation`: resumed that interrupted checkpoint for **2 additional updates**.
Final metadata reports **3 completed updates**, not 2 and not 4. Direct inspection of these
trusted generated checkpoint files confirmed Adam step counters **20 → 60** and the backend
common-step counter **24 → 72**. The optimizer was continued, not reinitialized.
No long convergence run, scheduler restart/reboot recovery, or multi-GPU orchestration was tested.
Process-loss/PID-reuse guards are covered by process-level tests, not a power-loss experiment.
## Actual matrix and checkpoint selection
`runs/ops_g1_matrix` contains **32 completed cells**:
- 2 checkpoints: after update 1 and update 4;
- 2 evaluation seeds: 101 and 202;
- 4 commands: standing, forward, lateral, turn;
- 2 profiles: randomized and stress;
- each cell: **2 worlds × 150 control steps**, dt 0.02 s, episode limit 5 s.
Every cell recorded **2 distinct initial states out of 2 worlds**. Stress cells recorded **71 total
velocity-kick events**. Repeating the same stress seed/command produced exactly matching initial
state arrays; XY RMSE differed by about `1.88e-5 m/s`, demonstrating why seeded draws are not a
promise of bitwise deterministic CUDA trajectories.
`table.csv`, `table.md`, and `summary.json` contain seed-level means/sample variances, failure
metrics and censoring. This 3 s observation horizon is intentionally short for engineering checks,
not sufficient policy acceptance evidence.
`runs/ops_g1_selection.json` ranked the earlier checkpoint first by equal-weight mean failure
incidence: **0.3333 vs 0.3750 events per simulated world-second**. This is not a general quality
ranking. Both policies fall; more updates did not automatically produce a better measured result.
`runs/ops_g1_baseline_matrix` and `runs/ops_g1_candidate_matrix` are single-checkpoint views copied
from the same 32 real cells, not additional independent experiments. `compare` successfully
produced paired-seed differences in `runs/ops_g1_comparison.json`.
## Training curves, not time spent
`runs/ops_g1_curves` contains JSON, CSV and parseable SVG extracted from actual TensorBoard events:
| Scalar | First | Last | Samples |
|---|---:|---:|---:|
| Linear tracking reward | 0.01648 | 0.05844 | 4 |
| Angular tracking reward | 0.004257 | 0.001208 | 4 |
| Mean action std | 1.00023 | 1.00013 | 4 |
| Mean episode length (control steps) | 12.0 | 51.65 | 4 |
Linear tracking/episode length increased, angular tracking decreased, and exploration std stayed
near 1. Four noisy points, random initial episode lengths and falling replays do **not** establish
learning or convergence. `/time` companion tags are no longer mislabeled as iteration curves.
## Measured replay and T1 coverage
| Evidence | Sampling | CSV rows | Failure events | Recorded kicks |
|---|---|---:|---:|---:|
| `runs/ops_g1_joints.csv` | 1 world × 150 steps × 29 joints | 4,350 | 1 | 2 |
| `runs/ops_t1_joints.csv` | 4 worlds × 150 steps × 23 joints | 13,800 | 6 | 7 |
Both used the stress profile and finite projected joint torques. CSV terminal-row counts matched
failure events × joint count (29 and 138), confirming terminal samples were retained before reset.
T1 recorded 4 distinct initial states out of 4 worlds. Its policy came from a separate two-update
run at `runs/ops_t1_validation`.
`runs/ops_g1_replay.mp4` decoded successfully: **150 frames, 50 FPS, 3 seconds**. A decoded frame
was visually inspected; robot and ground are visible. The matching measured report records a fall.
Interactive native/Viser viewing was not manually exercised in this revision.
A separate four-step evaluation, `runs/ops_g1_censored.json`, had no completed episodes:
completed-only failure fraction/return/duration were **null**, and both worlds were explicitly
censored rather than reported as successful episodes.
## Export regression and provenance
The updated evaluation report was accepted by ONNX export; `runs/ops_g1_bundle` passed
`verify-bundle --inference`. All outputs remain `hardware_approved: false`.
Earlier `ops_*_v1` development runs are retained. They predate the TensorBoard time-axis correction
and other final source changes and intentionally fail current source-identity checks. Historical
`g1_validation` / `t1_validation` runs also require their recorded sources for replay. Do not
rewrite provenance hashes to make old runs appear current.
+119
View File
@@ -0,0 +1,119 @@
# Vendoring, installation and robot-gate validation
Measured on **2026-11-03**, Linux x86-64 / RTX 5080. This revision replaces the external-backend
bootstrap with installed vendored packages. Evidence paths below are ignored development
artifacts, not files shipped in a fresh clone. Different hardware/platforms still need validation.
These measurements predate Git initialization and the subsequent license/CI-tool-lock changes.
Historical checkpoints retain their recorded lock and source identities; do not rewrite those
identities to replay them against a changed lock. Repository/CI checks are recorded separately in
[Repository baseline](REPOSITORY_BASELINE.md).
## Source and dependency boundary
- `rl/mjlab`: baseline commit `8bb2bc9e187797689ec82c78c35019afd2fd0376`, two captured runtime
patches and the included T1 adapter; details in [VENDOR.md](VENDOR.md).
- `rl/rsl_rl`: 5.5.1 Python files verified against installed release RECORD hashes before copying.
- Booster T1 asset source: commit `12a97516f57469078707afb587a5f84c1cb110d1`; only the selected
XML and referenced meshes are bundled, with their BSD license.
- Current vendor inventory: **355 non-cache files**, no missing/changed/extra files.
- `uv.lock`: **154 package records** including this project. The hashed pip export contains the
matching **153 external name/version pairs**; layout tests enforce this correspondence.
- New project `.venv` installed with `uv sync --locked --extra dev --python 3.13`:
Python **3.13.16**, Torch **2.14.0+cu130**, MuJoCo/MuJoCo Warp **3.16.0**, Warp **1.18.0**.
Dependency consistency and installed backend-origin checks passed; no separate mjlab/RSL-RL
distributions are installed in it.
The first large Torch download attempt timed out; a subsequent download/installation completed.
The external reference environment and source repositories were not modified. The validated
runtime does not import backend code from them.
## Automated and core-only checks
`./scripts/check`: **93 tests passed**, Ruff lint/format passed; one upstream TorchScript
warning remains. New coverage includes manual index/link/CLI synchronization, private-path and
sys.path rules, vendor drift, lock/export correspondence, installed origins outside the repo,
bad explicit interpreter/backend overrides, and negative robot-contract cases.
A separate lightweight environment installed the project with `--no-deps` plus pytest:
**76 passed, 3 skipped**. GPU/backend-dependent modules were deliberately skipped; this verifies
the core/layout CI path, not simulator functionality. The GitHub workflow is configured but has
not been executed on hosted GitHub infrastructure here.
## Actual robot gates
The setup-env check script completed all five gates—vendor, runtime, dependencies, robot and
GPU smoke—for both example configurations:
| Report | Robot checks | Probe | Peak left/right contact force | Initial penetration |
|---|---:|---|---|---:|
| `runs/setup_vendor_g1/robot.json` | 11/11 passed | 32 steps, no termination | 535.05 / 535.13 N | 0 m |
| `runs/setup_vendor_t1/robot.json` | 11/11 passed | 32 steps, no termination | 460.06 / 460.04 N | 0 m |
Forces are transient simulated contact measurements during the nominal drop/PD probe, not certified
load ratings or calibrated hardware force estimates. Sites, local frames, IMU parent/type, joint
orders, gains/limits, initial pose/velocity and timing were checked against separate declarations.
An intentionally wrong G1 declaration required a nonexistent foot site. The real CUDA gate returned
**exit 1**, `ready: false`, with **only `foot_sites` failing**; the other ten checks still ran.
Evidence: `runs/negative_robot_spec.json`, `runs/negative_robot_check.json`. This was not just a
mocked negative test. Additional unit cases corrupt IMU frames, positions, PD, order, collisions,
contact force, initial velocity, penetration and finite-state/termination behavior.
## Relocated checkout, new environment, different working directory
A copy excluding `.venv`, runs, caches and build outputs was placed under a temporary directory
whose checkout name contained a space. A **separate environment** was installed there using
`uv sync --locked --offline --extra dev --python 3.13`, using downloaded public wheel cache entries.
No original backend checkout or virtual environment was on its import path.
The subprocess environment removed `PYTHONPATH`, `MJLAB_ROOT`, `BOOSTER_ASSETS_ROOT`,
`UNITREE_ROBOTS_ROOT`, `UH_PYTHON` and `UH_EXTRA_PYTHONPATH`. From **outside that checkout**:
1. Backend origins, lock versions and CUDA passed.
2. Vendor inventory passed.
3. Bundled T1 robot gate passed.
4. T1 PPO → randomized evaluation → ONNX export completed.
5. Bundle inference verification passed.
Evidence: `runs/portability_relocation_v2.json`, `runs/portability_relocation_v2.log`,
`runs/relocated_t1_check_v2.json`, and a retained copy at `runs/relocated_t1_pipeline_v2/`.
This proves independence from the prior workspace layout on the tested host. It is not a test
on a second GPU/OS or a claim that an existing editable virtualenv can be moved without reinstalling.
## Wheel resource and installed-package checks
An initial wheel parity check caught missing `mjlab/scripts/train.py`: namespace discovery had
been disabled. Packaging now includes namespaces; a layout assertion, `tools/check_wheel.py`
and the CI build/parity step guard the regression.
The corrected wheel passed **370 exact file comparisons**, including backend Python modules,
T1/G1 model resources, license files and robot-spec JSONs. It was then installed in the relocated
environment, replacing only the editable project distribution. Imports resolved to the wheel's
`site-packages`, not either checkout. T1's actual robot gate passed again from outside the repo:
`runs/wheel_validation_v2.log`, `runs/wheel_t1_check_v2.json`.
## Training/export regression
Both final pipelines used **16 environments × 2 PPO updates × 24 steps**, followed by
**2 evaluation worlds × 150 steps**:
| Run | Failures in evaluation | ONNX max absolute error (16 actual observations) |
|---|---:|---:|
| `runs/vendored_g1_pipeline_v2` | 3 | 5.59e-8 |
| `runs/relocated_t1_pipeline_v2` | 2 | 4.66e-8 |
Both bundles passed inference verification. `runs/vendored_resume_v2` also resumed G1 for one
additional update as an installed background worker; progress reached **3 total updates**.
No validation workers were intentionally left running.
These short policies still fall. Adapter conformance, installation portability and export parity
are engineering checks—not proof of learned walking or real-robot safety. Older validation
runs retain their original source/dependency identities and require their recorded environment
for replay. Do not rewrite historical hashes after vendoring.
## Remaining release work
Original code now has an Apache-2.0 license. Review downstream attribution, set actual hosting
metadata, and validate additional hardware/driver/platform combinations. The dependency lock
cannot provide a driver, certify dynamics or substitute for a hardware safety controller.
+50
View File
@@ -0,0 +1,50 @@
# Public release checklist
A public repository description should explain the reusable framework, not assume access to a
maintainer's workstation. Documentation portability and executable portability are separate tasks.
This checklist records what is still needed before describing the project as a reproducible,
ready-to-install release.
## Packaging and dependencies
- [x] Include backend copies, required G1/T1 adapters/assets, source inventories and license notices; see `VENDOR.md`.
- [x] Publish `uv.lock`, its hashed pip export and reference CUDA/platform guidance.
- [x] Remove personal workspace defaults from launchers, T1 and asset discovery.
- [x] Reject bad explicit interpreter paths and legacy external-backend overrides.
- [x] Install the lock in a new project environment without the external backend environment.
- [x] Test a relocated checkout/new environment from another working directory, plus wheel resource parity and installed T1 conformance; see `PORTABILITY_VALIDATION.md`.
- [ ] Independently validate additional machines/GPUs and any additional platform-specific lock.
- [x] Document bundled model variants/licenses and explicit optional external overrides.
## Repository presentation
- [x] Use audience-neutral English and Chinese introductions and configurable-path command examples.
- [x] Distinguish architectural goals, implemented features, reference validation and unsupported capabilities.
- [x] Document setup requirements and current distribution limitations.
- [x] Add Apache-2.0 for original code, retain third-party licenses, and include license texts in package metadata. `NOTICE.md` remains attribution, not a replacement license.
- [ ] Set the actual repository URL and package metadata when hosting is established; do not publish placeholder links as real project URLs.
- [x] Add contribution guidance, stage manuals, synchronization tests and core/layout CI configuration.
- [ ] Configure a GPU CI runner and hosted issue templates when the repository is published.
Suggested GitHub repository description:
> An agent-ready framework for modular humanoid reinforcement learning with mjlab and MuJoCo Warp: reward iteration, training, evaluation, replay, and ONNX export.
Suggested topics: `humanoid-robotics`, `reinforcement-learning`, `mujoco`, `mjlab`, `robot-learning`,
`ai-agents`, `sim-to-real` (research direction, not a claim of hardware deployment support).
## Artifacts, privacy and claims
- [ ] Inspect the actual files staged for publication. Ignore rules do not remove files already tracked by Git.
- [ ] Exclude credentials, `.env`, virtual environments, proprietary meshes and unlicensed third-party files.
- [ ] Review run manifests, logs and archives for usernames, absolute paths, git status and source licensing before sharing them as release assets.
- [ ] Do not present development-only `runs/` paths as downloadable artifacts unless those artifacts have actually been published.
- [ ] Separate successful pipeline execution from policy convergence; include failed episodes and evaluation protocol details.
- [ ] Preserve `hardware_approved: false` and the absence of a physical robot execution interface.
## Release validation
Run lint/unit tests, selected adapter tests, GPU smoke, bounded training, fixed-protocol evaluation,
video recording and ONNX parity in the documented release environment. Record commit and dependency
identities alongside measured evidence. Existing historical validation is useful context, not a
substitute for verifying the released revision on a clean installation.
+43
View File
@@ -0,0 +1,43 @@
# Repository baseline
This directory is a standalone Git repository on `main`. The initial snapshot includes source,
vendored backends/assets, licenses, experiment recipes, manuals, tests, CI and dependency locks.
No remote is configured or pushed automatically. Configure your actual hosting URL before pushing;
do not reuse the reference project's remote.
## License
Original code and documentation use Apache-2.0, following Jumper. The unmodified license text
is in [LICENSE](../LICENSE); project attribution and third-party obligations are in
[NOTICE.md](../NOTICE.md). Existing Apache/BSD/MIT vendor licenses remain intact. Package metadata
uses the combined `Apache-2.0 AND BSD-3-Clause AND MIT` expression for the distribution, with
license texts included in the wheel.
## Locks and CI
- `uv.lock`: complete reference Linux CUDA dependency resolution, plus the lightweight CI group.
- `requirements-linux-cu130.lock`: hashed pip export for the development/training environment.
- `requirements-ci.lock`: hashed pip export for check/build tools only, without Torch/CUDA.
- `.github/workflows/check.yml`: immutable action revisions, pinned uv, locked check/build tools,
lock/export synchronization, vendor inventory, wheel parity, Ruff and core/layout tests.
The CI job does not run GPU simulation. Hosted Actions only run after publication on GitHub;
local reproduction is not a claim of a hosted green build. See [Setup](SETUP.md) for commands.
## Local verification
The full configured environment passed **94 tests** and Ruff lint/format checks. A separate
locked CI-only environment passed **77 tests, 3 skipped**; GPU/backend-dependent tests were
intentionally skipped. Wheel parity checked **370 package files** plus **7 distribution license
files** and the SPDX metadata expression. Both requirements exports were regenerated from the lock without drift.
The staged snapshot was reviewed for generated files, symlinks, oversized files, personal
workspace paths and common secret formats. `.venv*`, runs, logs, bundles, build output, caches,
checkpoints, `.env` variants and private-key files are excluded. This screening is not a guarantee
that no possible sensitive information exists; review changes before publishing.
## Provenance boundary
Existing runs remain untouched. Git initialization and lock updates are not retraining or renewed
GPU acceptance evidence. Historical runs keep their original source/lock identities; restore their
trusted recorded environment when needed rather than modifying provenance to force reuse.
+162
View File
@@ -0,0 +1,162 @@
# Environment setup
The simulation/learning sources are **vendored in this repository**:
`rl/mjlab` and `rl/rsl_rl`. G1 and T1 models required by the registered examples are also bundled,
with their licenses. No external mjlab checkout, personal directory layout or asset download is
needed for these examples. See [VENDOR.md](VENDOR.md) for exact origins and retained modifications.
## Supported reference target
The locked training target is **Linux x86-64, Python 3.11–3.13, NVIDIA CUDA 13.0 PyTorch**.
Python 3.13 is the tested interpreter. A compatible NVIDIA driver is required; the Python lock
cannot install a driver or guarantee support for every GPU. EGL is the default offscreen renderer.
Other OS/architectures and CUDA builds need a separately validated lock; there is no native-CPU
training fallback.
Before installing, the standard-library detector works without simulation packages:
```bash
python3 .agents/skills/setup-env/scripts/detect.py
```
## Recommended: locked installation in a new environment
Install `uv`, then run from the repository root:
```bash
uv sync --locked --extra dev --python 3.13
./scripts/uh doctor
./scripts/uh verify-vendor
./scripts/check
```
`uv.lock` pins transitive dependencies and artifact hashes, including the PyTorch CUDA index and
NVIDIA Warp index. `--locked` refuses to silently resolve a changed project. `uv sync` installs
this project as editable and creates `.venv`; it does not reuse another project's environment.
Large CUDA wheels may take time to download. Do not interpret a partial download as an installed
runtime.
## Standard pip editable installation
The same packaging layout supports `pip install -e .`, as in Jumper. **mjlab and rsl_rl are included
in this distribution**, not separately installed PyPI packages. Always use a fresh virtual environment:
```bash
python3.13 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
```
This convenient command resolves the declared dependencies but does not enforce the entire
transitive lock. For the locked pip alternative, install the exported requirements first:
```bash
.venv/bin/python -m pip install --require-hashes -r requirements-linux-cu130.lock \
--extra-index-url https://download.pytorch.org/whl/cu130 \
--extra-index-url https://pypi.nvidia.com/
.venv/bin/python -m pip install --no-deps -e .
```
The exported file contains exact versions and hashes. It targets the same Linux CUDA environment,
not all platforms. Regenerate it from `uv.lock`, never edit it by hand:
```bash
uv export --locked --extra dev --no-emit-project --format requirements-txt \
--output-file requirements-linux-cu130.lock
```
Do not install `mjlab` or `rsl-rl-lib` separately. `doctor` checks package origins and detects
conflicting distributions. Repair a polluted environment by creating a new one, not by uninstalling
packages from another project's shared runtime. Installed wheels include the same model resources
and licenses; the source inventory check itself requires a repository checkout.
## Lightweight CI environment
`.github/workflows/check.yml` checks locks, licenses/layout, source inventory, wheel resource
parity, lint/format and core tests on hosted Linux/Python 3.13. Actions use immutable revisions;
the resolver is version-pinned. No GPU runtime is installed by this job, so backend-dependent
tests skip rather than claiming a simulator pass. The GPU gates below remain separate.
The `ci` dependency group is locked in `uv.lock`. Its small hashed pip export is
`requirements-ci.lock`; regenerate it with:
```bash
uv export --locked --only-group ci --no-emit-project --format requirements-txt \
--output-file requirements-ci.lock
```
CI regenerates both exports and rejects Git diffs. To reproduce its environment without replacing
your training `.venv`, use another directory:
```bash
UV_PROJECT_ENVIRONMENT=.venv-ci uv sync --locked --only-group ci --python 3.13
uv pip install --python .venv-ci/bin/python --no-deps --no-build-isolation -e .
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 .venv-ci/bin/python -m pytest -q
```
The wheel is built with `--no-isolation`, using the locked build tools, rather than downloading
an unpinned build environment. CI is triggered by pushes, pull requests and manual dispatch after
this repository is hosted on GitHub; a local Git commit does not itself execute GitHub Actions.
## Run the setup gates
```bash
.venv/bin/python .agents/skills/setup-env/scripts/check.py \
--config experiments/g1_smoke.json --output runs/setup-g1
.venv/bin/python .agents/skills/setup-env/scripts/check.py \
--config experiments/t1_smoke.json --output runs/setup-t1
```
The script runs vendor inventory, backend/CUDA/version checks, dependency consistency,
`check-robot`, and a bounded GPU smoke. It preserves a log for every gate and a JSON summary;
any failed gate gives a nonzero exit. It does not install packages, change gains, repair assets
or weaken checks. Use a new output directory each time.
`check-robot` validates declared interfaces AND measured contact response; it does not prove
locomotion or physical safety. See [NEW_ROBOT.md](NEW_ROBOT.md).
## Interpreter and optional asset configuration
`scripts/uh` chooses an explicit executable `UH_PYTHON`, otherwise the project `.venv/bin/python`,
otherwise `python3` from PATH. The project must be installed in that interpreter. A bad explicit
path fails; it never falls back to another project's environment. The launcher clears inherited
`PYTHONPATH`/user-site leakage and does not inject source directories. An installed `uh` entry
point also works from outside the repository.
`scripts/uh` rejects legacy `MJLAB_ROOT` and `UH_EXTRA_PYTHONPATH` overrides. Unset them when migrating.
The installed Python entry point also enforces vendored import origins; those old variables cannot select a backend.
Use `UH_PYTHON` only to select another **installed, compatible** environment.
Optional external asset discovery/override:
```bash
export UNITREE_ROBOTS_ROOT=/path/to/unitree_ros/robots
./scripts/uh assets
./scripts/uh inspect-asset "$UNITREE_ROBOTS_ROOT/g1_description/g1_29dof.xml"
# Optional T1 replacement, not required for the bundled example:
export BOOSTER_ASSETS_ROOT=/path/to/booster_assets
```
An explicit Booster override expects `robots/T1/T1_23dof.xml` and referenced meshes. An invalid
override fails rather than silently using the bundled asset. G1 training uses the bundled adapted
G1 model, not Unitree ROS XML. External model changes require a new conformance report and source/
asset provenance; an inventory entry is not a registered task.
## Lightweight configuration inspection
`list` and `plan` do not import the simulation stack. If intentionally inspecting source without
an install, `PYTHONPATH=src python -m universal_humanoid list` remains a metadata-only convenience;
it is **not** a supported way to select a training backend.
## Troubleshooting
- **Backend shadowing:** inspect `doctor` origins. Both backends must resolve to this checkout's
`rl/` (editable install), or the packages installed by the same built wheel.
- **Core version mismatch:** restore the documented lock in a new environment.
- **No CUDA:** check driver compatibility and GPU access; CPU discovery is not a training pass.
- **Vendor mismatch:** inspect the diff against `rl/VENDOR.json` / `rl/upstream/import.json`;
do not regenerate the inventory just to hide an unexplained change.
- **Robot gate failed:** read the failed check IDs and actual/declared values. Do not widen a
tolerance or remove a foot/sensor requirement merely to turn the report green.
- **Historical run rejected:** restore its trusted recorded source/assets/dependencies separately;
vendoring intentionally changes provenance. Do not rewrite old hashes.
+205
View File
@@ -0,0 +1,205 @@
# Training operations and experimental evidence
Training duration is not evidence of learning. Read tracking curves, exploration noise and
completed episode lengths during training; then measure the policy under explicit evaluation
conditions. These commands use the same configured runtime as the main README.
## 1. Train in the foreground or background
```bash
./scripts/uh train --config experiments/g1_flat.json --output runs/g1-baseline --background
./scripts/uh status runs/g1-baseline
./scripts/uh checkpoints runs/g1-baseline
./scripts/uh stop runs/g1-baseline
```
Omit `--background` for foreground training. Background execution is a **local Linux process**,
not a remote scheduler or reboot-persistent service. It uses the selected Python environment,
redirects stdout/stderr to `runs/g1-baseline.job/stdout.log`, and disconnects stdin/session from
the launching terminal. No TensorBoard HTTP server is started.
`status` is machine-readable JSON: process liveness, effective state, latest committed checkpoint,
completed/target iterations, session environment steps, iteration duration, learning rate,
action standard deviation, losses, last-update age and an approximate ETA. ETA includes setup
cost and is not an acceptance metric. Progress updates once per completed optimizer iteration;
a long compilation/rollout may be alive without a new progress record. A dead worker whose
manifest still says running is reported as `lost`, not completed.
`stop` sends SIGTERM to the recorded process, guarded by Linux process identity and pidfd to
avoid signaling a reused PID. Poll `status` until termination. Graceful interruption preserves
previous committed checkpoints; an incomplete optimizer update is not saved as a usable model.
SIGKILL, OOM or power loss may leave temporary files; only checkpoints published in the manifest
are usable. Failed runs and job logs are retained.
Set `checkpoint_interval` in an experiment JSON to control periodic saves (default 50 optimizer
iterations). The backend also saves after its first update and at completion. Each checkpoint
is written to a temporary file, renamed, hashed and committed to `run.json`. Published files
are immutable; new experiments and resumes always use **new output directories**.
## 2. Resume a specific checkpoint
```bash
./scripts/uh train --resume runs/g1-baseline/model_49.pt \
--iterations 200 --output runs/g1-continued --background
```
`--iterations 200` means **200 additional updates**, not a total of 200. Choose a filename from
`checkpoints`; do not assume `model_49.pt` exists. `model_N.pt` stores the zero-based last update:
`model_49.pt` represents 50 completed updates, so its continuation starts with update index 50.
The manifest records `completed_iterations` to remove this ambiguity.
Resume restores actor, critic, observation normalization, optimizer state (including learning
rate), and the backend's common-step curriculum counter. Simulator state, pending rollouts,
random-number state and logger history restart: this is **learning continuation, not bitwise
trajectory replay**. The new run records parent checkpoint and experiment hashes. Code, assets,
dependencies and experiment settings must match; only the additional iteration budget and
checkpoint interval may change. Older checkpoints lacking explicit completed-update metadata
are not accepted for continuation.
A committed intermediate checkpoint may be evaluated or resumed even if its original run is
still training or was interrupted. Export still requires a completed training run. Uncommitted
files are never recovered by guessing their modification time.
## 3. Inspect TensorBoard curves without a server
```bash
./scripts/uh curves runs/g1-baseline --output analysis/g1-curves --window 20
# Inspect another set of scalar tags:
./scripts/uh curves runs/g1-baseline --output analysis/g1-losses --match 'Loss/|Metrics/'
```
Outputs:
- `curves.json`: all selected scalar samples, available tags, missing categories, first/last
values, min/max, recent-window mean and slope per iteration.
- `curves.csv`: tag, scalar step, step-axis type, wall-clock timestamp, value.
- `curves.svg`: independently labelled panels; no GUI or plotting dependency required.
By default, select tracking terms (`Episode_Reward/track_*`, velocity-error metrics),
`Policy/mean_std`, `Train/mean_episode_length`, total reward and curriculum terms. The command
excludes RSL-RL's duplicate `/time` tags by default; if explicitly matched, these are labelled
elapsed seconds, not iterations, and their slopes are per second. It reads scalar TensorBoard
events directly in the specified run directory, including while a
training process is active. It does not recursively mix different runs. Duplicate steps use the
latest wall-time sample; non-finite points are counted and excluded, not disguised as zeros.
A missing curve is reported as missing. Episode metrics may not exist until episodes finish.
Interpret together:
- Rising total reward with flat tracking may reflect regularizer exploitation rather than command following.
- Inspect action standard deviation together with learning rate/losses; a plateau alone does not diagnose its cause.
- Check episode length, failure events, command coverage and video—not just a smooth reward curve.
- Tracking rewards are weighted training terms, not physical RMSE or calibrated success probabilities.
No curve slope automatically declares convergence or approves a policy.
## 4. Evaluate independent initial-state draws and disturbances
```bash
./scripts/uh evaluate --checkpoint runs/g1-baseline/final.pt \
--output analysis/g1-stress.json --seed 101 --profile stress \
--command 0.3 0 0 --num-envs 8 --steps 1000
```
Profiles are versioned in the recorded `fixed-twist-v2` protocol:
| Profile | Initial state on every reset | Actor observation noise | Interval disturbances |
|---|---|---|---|
| `nominal` | Fixed pose/joints/velocity | Off | None |
| `randomized` (evaluation default) | Separate uniform samples for each world | Off | None |
| `stress` | Same reset distribution as randomized | Configured task noise enabled | Per-world random velocity kicks |
Randomized reset offsets: root x/y ±0.1 m, z +0.01…0.03 m, roll/pitch ±0.03 rad, yaw ±0.2 rad;
root x/y velocity ±0.05 m/s, yaw rate ±0.1 rad/s; joint position ±0.03 rad and velocity ±0.1 rad/s.
Joint positions are clamped to the adapter's soft limits. Root offsets are relative to the robot's
default root state and world origin. These are modest test distributions, not physical validity
guarantees for future adapters.
Stress kicks add x/y velocity increments within ±0.4 m/s and yaw-rate increments within
±0.5 rad/s, at independently sampled 0.5–1.5 s intervals per world (timers restart on reset).
These are **mass-independent instantaneous velocity changes**, not force-calibrated pushes.
Training startup mass/friction/COM randomization is not enabled by these profiles; this is not a
complete sim-to-real robustness suite.
Reports include all initial states relative to world origins, unique-state counts, exact reset
ranges, actor noise definitions, per-world kick counts, failure counts and first-episode censoring.
A short rollout may experience no kick; inspect the actual counts. Repeating a seed reproduces
initial-state draws, but CUDA trajectories are not guaranteed bitwise deterministic. Distinct world samples share
a policy and are not independent training replicas. Nominal replicas remain intentionally fixed.
## 5. Run a checkpoint × seed × four-command matrix
```bash
./scripts/uh benchmark \
--checkpoints runs/g1-baseline/model_0.pt runs/g1-baseline/final.pt \
--seeds 101 202 303 --profiles randomized stress \
--steps 1000 --num-envs 8 --output analysis/g1-matrix
```
The four commands are standing `(0,0,0)`, forward `(0.3,0,0)`, lateral `(0,0.2,0)`, and turn
`(0,0,0.3)`. This example has 2 × 3 × 2 × 4 = **48 evaluation cells**, executed serially to bound
GPU memory. `summary.json` updates after every cell and records failures; completed cells are
retained, but automatic continuation of an interrupted matrix is not implemented.
Outputs include per-cell reports and aggregate `table.csv` / `table.md`:
- Mean and **sample variance across evaluation seeds**, with the number of defined values.
- XY/yaw RMSE, completed-episode duration and failure metrics.
- **Failure fraction among completed episodes** = failures / completed episodes; null if none ended.
- **Failure incidence** = failure events / simulated world-seconds, including repeated episodes.
- **First-episode failure fraction** = worlds whose first episode failed within the observation
horizon / worlds. Report censoring alongside it; unfinished episodes are not proven successes.
Variance is null with fewer than two values. Never treat repeated world resets as independent
training seeds. If a termination and timeout coincide, failure takes precedence. Means weight
seed-level reports equally; the table also supplies raw completion/failure counts. Long-lived
censored episodes can bias completed-only statistics, so inspect the entire set of metrics.
`--seeds` changes **evaluation randomness**, not training seeds. For training-seed robustness,
train separate experiment JSONs with different `seed` values, then pass their checkpoints to
this command. Results remain separated by checkpoint, with each training seed recorded.
### Select, compare, then validate on held-out seeds
```bash
./scripts/uh select-checkpoint analysis/g1-matrix/summary.json \
--metric failure_events_per_sim_second --output analysis/g1-selection.json
# Each input here must be a completed matrix containing one checkpoint:
./scripts/uh compare analysis/baseline-matrix/summary.json analysis/candidate-matrix/summary.json
```
Selection ranks the **explicit candidate list**, equally weighting command/profile mean values
for a named lower-is-better metric. No undefined cells are accepted. Ties retain input order;
there is no hidden composite quality score or hardware promotion. The selection file references
the checkpoint; it does not overwrite `final.pt`. Evaluate the winner on held-out seeds and
inspect tracking/video, since low failure incidence alone can favor standing still.
Matrix comparison reports paired candidate-minus-baseline means and sample variances by seed,
command and profile. It refuses mismatched protocols; it does not claim statistical significance.
The original two-single-report comparison remains available for quick diagnostics.
## 6. Replay with joint measurements
```bash
./scripts/uh play --checkpoint runs/g1-baseline/final.pt \
--measure analysis/g1-joints.csv --steps 1000 --seed 101 \
--profile stress --command 0.3 0 0 --video analysis/g1-replay.mp4
```
`play --measure` is a **bounded headless replay**, not an interactive viewer session. Without
`--measure`, `play --viewer native|viser` retains the interactive viewer. For multiple worlds,
use `evaluate --measure FILE --num-envs N`.
The long-form CSV has one row per controlled joint × world × control step: global and episode
time, world/episode IDs, termination/timeout flags, joint name, position (rad), velocity (rad/s),
actuator contribution to joint torque (Nm), raw/applied action and actual joint target.
Simulation uses manual resets during evaluation. CSV and video are sampled **after the control
step but before resetting ended worlds**. Torque is `qfrc_actuator` projected into joint DOFs,
not motor-space force, a desired torque, or a decimation-averaged value. Sampling is at policy
rate; substep peaks may be missed. A `.csv.json` sidecar records schema semantics, row count and
completion/failure status; `.evaluation.json` contains task metrics.
All commands remain simulation-only. These measurements do not replace hardware sensing,
transport adapters, safety supervision or sim-to-real validation.
+103
View File
@@ -0,0 +1,103 @@
# Reference-environment validation
For current vendored installation, relocated-checkout/wheel tests and automatic robot gates,
see [Portability validation](PORTABILITY_VALIDATION.md).
For the subsequent background/resume, randomized matrix evaluation, TensorBoard and CSV work,
see [Training-operations validation](OPERATIONS_VALIDATION.md). The sections below preserve the
initial pipeline validation and its original source/protocol version.
This is a historical validation record for one development configuration, not a minimum
hardware specification or a guarantee of compatibility with every installation. See
[Setup](SETUP.md) for environment requirements and [Releasing](RELEASING.md) for distribution
limitations. Paths under `runs/` below identify development artifacts; they are ignored by Git
and are not bundled with a repository checkout or offered here as downloads.
Measured on **2026-11-03**, NVIDIA GeForce **RTX 5080, 16 GB**, in a reference mjlab
Python 3.13 environment. These results validate engineering plumbing, **not learned locomotion**.
## Runtime
| Component | Observed version |
|---|---|
| mjlab | 1.6.0, customized checkout |
| mjlab git HEAD | `8bb2bc9e187797689ec82c78c35019afd2fd0376` (dirty/untracked changes retained) |
| MuJoCo / MuJoCo Warp | 3.16.0 / 3.16.0 |
| Warp | 1.18.0 |
| PyTorch | 2.14.0+cu130 |
| RSL-RL | 5.5.1 |
The exact Python/asset hashes and dirty git status are in each `train/run.json`. The reference
repositories were not modified. `sources.zip` preserves 230 Python/license entries per final run.
Do not replace the customized dependency with a public version just because its version number matches.
## Automated checks
`./scripts/check`: **35 tests passed**, Ruff lint and format checks passed. One upstream
`torch.jit.script` deprecation warning remains. Tests cover strict configs, lightweight discovery,
independent factories, reward shape/sign, unknown overrides, retained evaluation terminations,
source/experiment/checkpoint drift, partial-run rejection, bundle tampering/path traversal and
protocol mismatch.
An initial direct pytest invocation inherited ROS's Python 3.12 plugin path and failed on a missing
`lark` import. The project check script excludes inherited ROS paths and disables unrelated pytest
plugin autoload; no external Python environment was modified.
## Actual CUDA simulation and PPO
Zero-action checks ran for G1 and T1 with 4 environments and 8 steps; observations and rewards
were finite. Shapes: G1 actor/critic/action = **99 / 111 / 29**; T1 = **81 / 93 / 23**.
Final end-to-end runs each used **16 environments, 2 PPO iterations, 24 rollout steps per iteration**
(768 collected environment transitions), then **4 evaluation worlds × 500 steps**, dt 0.02 s,
5 s episode limit, fixed command `(0.3, 0, 0)`, seed 42.
| Run directory | XY tracking RMSE (m/s) | Yaw RMSE (rad/s) | Failure events | Mean completed episode (s) | ONNX max abs error |
|---|---:|---:|---:|---:|---:|
| `runs/g1_validation` | 0.709230 | 0.322807 | 24 | 1.500 | 5.59e-8 |
| `runs/t1_validation` | 0.480955 | 0.047538 | 24 | 1.560 | 5.96e-8 |
| `runs/g1_reward_validation` | 0.675789 | 0.313275 | 24 | 1.480 | 5.22e-8 |
**All three policies fall. None is a deployment candidate.** Failure events count repeated
episode failures across resets, not a probability. The current nominal evaluation deliberately
uses identical resets in parallel worlds; those worlds are not independent statistical trials.
The small candidate RMSE difference is not evidence of an improved learned policy after two updates.
Each run has `pipeline.json`, `train/final.pt`, `evaluation.json`, and `bundle/`.
`verify-bundle --inference` passed for G1 and T1. ONNX parity was checked against the PyTorch actor
at 16 actual rollout observations for every export. The reward candidate exercises local reward
function injection, training, evaluation, export and protocol-matched comparison.
## Replay evidence
`runs/t1_validation/replay.mp4`: H.264, **100 frames / 2 s / 50 FPS / 320×240**;
`video_evaluation.json` is the corresponding one-world report. Encoding and decoding succeeded,
and a decoded frame was inspected: the T1 and ground are visible, not an empty render.
This replay also records an episode failure. Desktop native and interactive Viser sessions were
not manually exercised; their CLI paths use mjlab's existing viewer classes.
## External Unitree asset checks
Native MuJoCo compilation succeeded for:
- `unitree_ros/robots/g1_description/g1_29dof.xml`: nq=36, nv=35, nu=29.
- `unitree_ros/robots/h1_description/mjcf/h1.xml`: nq=26, nv=25, nu=19.
These are **asset compilation checks only**. They are not registered RL task adapters; the
validated G1 training run uses mjlab's adapted G1 asset. T1 training uses an external Booster
T1 asset through the registered adapter.
## Failed development runs retained
`runs/g1_smoke_v1` trained but evaluation failed because the upstream command rejected
`heading_command=False` with a non-null heading range. The adapter now clears the heading range
and regression tests check evaluation configuration. `runs/g1_smoke_v2` passed an earlier short
pipeline before the final provenance/archive changes. Its old checkpoints intentionally fail
current source identity checks; use the final `*_validation` runs above.
## Remaining validation
Long-run convergence, gait quality, domain-randomized/stress evaluation, independent seeds/reset
conditions, contact realism, raw Unitree asset adaptation, rough terrain, motion imitation,
sim-to-sim dynamics parity and all physical deployment safety remain unverified/unimplemented.
No long 3,000-iteration recipe, robot transport or motor-enable operation was executed.
+79
View File
@@ -0,0 +1,79 @@
# Vendored backend sources and assets
Like Jumper's `rl/` layout, this project installs backend copies as **top-level packages** through
`pip install -e .` / `uv sync`, not through working-directory-dependent import tricks.
`rl/` deliberately has no `__init__.py`. Package discovery includes namespaces: upstream's
`mjlab/scripts` has no initializer but still contains real source that must be included in wheels.
| Path | Source | Baseline | License |
|---|---|---|---|
| `rl/mjlab/` | [mujocolab/mjlab](https://github.com/mujocolab/mjlab) plus recorded local changes | 1.6.0, commit in `rl/upstream/import.json` | Apache-2.0; embedded components retain their licenses |
| `rl/rsl_rl/` | Installed `rsl-rl-lib` release, checked against its distribution RECORD hashes | 5.5.1 | BSD-3-Clause |
| `rl/mjlab/asset_zoo/robots/booster_t1/assets/` | [BoosterRobotics/booster_assets](https://github.com/BoosterRobotics/booster_assets) | `T1_23dof.xml` and its referenced meshes; commit recorded | BSD-3-Clause |
| `rl/mjlab/asset_zoo/robots/unitree_g1/` | mjlab's adapted MuJoCo Menagerie model | Preserved with upstream mjlab assets | Unitree BSD-3-Clause |
## What was imported
The mjlab copy contains tracked package files from the validated checkout, **including its two
modified runtime files**, plus the T1 robot/task Python modules. Unrelated private/untracked
Apollo/R1 experiments, prompts, logs, environments and keyboard applications are not imported.
Other tracked upstream example assets remain intact; their presence does not register them as
supported Universal Humanoid tasks.
RSL-RL Python files were verified against the installed release's RECORD before copying. No
algorithm changes were applied. Its release METADATA and upstream mjlab pyproject are preserved
under `rl/upstream/`, without creating separately installed backend distributions.
## Explicit differences
| File | Origin / purpose |
|---|---|
| `rl/mjlab/sim/sim.py` | Retains the pre-existing local patch suppressing only LS_ITERATIONS/ITERATIONS warnings. This is **not** evidence of solver convergence; other overflow warnings remain. |
| `rl/mjlab/tasks/velocity/mdp/velocity_command.py` | Retains configurable `min_forward_velocity`; T1 uses a smaller minimum than G1. |
| `rl/mjlab/asset_zoo/robots/booster_t1/t1_constants.py` | The imported T1 adapter now defaults to bundled assets, with an explicit optional `BOOSTER_ASSETS_ROOT` override. No personal HOME fallback. |
| `rl/mjlab/tasks/velocity/config/booster_t1/` | T1 environment, PPO configuration and reward extension, previously external/untracked, now included. |
The first two inherited changes are preserved as the actual upstream-relative diff in
`rl/upstream/mjlab-local.patch`; their regression tests and the imported T1 test are retained in
`rl/upstream/tests/` as reference material. They are not automatically mixed into this project's
pytest suite. Our adapter/conformance/behavior tests exercise the supported integration.
Changed runtime files carry `[uh-vendor]` notices. The initial source inventory is
`rl/upstream/import.json`; the current distributable inventory is `rl/VENDOR.json`.
## Verify and update deliberately
```bash
python3 tools/vendor_manifest.py
./scripts/uh verify-vendor
```
Built-wheel resource parity can also be checked with
`python3 tools/check_wheel.py dist/universal_humanoid-0.2.0-py3-none-any.whl` after `uv build --wheel`.
It checks all package sources, model resources and licenses against the checkout, catching missing
namespace modules that an editable install could conceal.
Both inventory commands compare every non-cache file under `rl/` against recorded SHA-256 hashes; extra, missing and
modified files fail. No updater runs automatically. For a reviewed vendor revision:
1. Record the upstream release/commit, licenses and inherited patches.
2. Make changes in this repository only, adding a clear modification notice to changed source.
3. Update this document and review the diff against the initial import inventory.
4. Run the adapter, negative conformance, setup and GPU pipeline checks.
5. Explicitly record the accepted files with `python3 tools/vendor_manifest.py --record`.
6. If dependencies changed, regenerate `uv.lock` and its pip export, and repeat clean-install checks.
A hash inventory detects accidental drift; it does not prove safety or authenticate arbitrary code.
A deliberate hash refresh without review defeats its purpose. Source snapshots/provenance now
include RSL-RL source identity, robot declarations and the dependency lock, not just mjlab.
## Licensing and distribution
License texts travel inside both package directories and are included as wheel resources. The
mjlab assets and Isaac Lab-derived helpers carry their corresponding license texts in
`rl/mjlab/licenses/`; RSL-RL's dependencies and pfrl attribution are under `rl/rsl_rl/licenses/`.
T1 assets carry their own `assets/LICENSE`. See [NOTICE.md](../NOTICE.md) for attribution.
The upstream licenses do not automatically choose a license for this project's original code or
settle authorship of downstream additions. Select that license and review downstream attribution
before announcing an open-source release. No credentials or proprietary robot transport code is
included, and no physical deployment support is implied.