Files
UniversalHumanoid/docs/PORTABILITY_VALIDATION.md
2026-11-03 19:46:08 +08:00

7.0 KiB
Raw Permalink Blame History

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.

Source and dependency boundary

  • rl/mjlab: baseline commit 8bb2bc9e187797689ec82c78c35019afd2fd0376, two captured runtime patches and the included T1 adapter; details in 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.