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

120 lines
7.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.