Files
UniversalTrain-ai/docs/REFACTOR_STATUS.md
T
chenlin c32df70326
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
release: v0.1 generic robot training and application platform
2026-11-05 11:05:01 +08:00

15 KiB

Generic platform refactor — development record

Work began 2026-11-04 17:51 China time. The authorized autonomous window ends 2026-11-05 08:51 China time. This record distinguishes implementation checks, measured simulation behavior, and hardware qualification. The implementation and validation snapshot was finalized at 20:54 China time on 2026-11-04. All training runs started for this snapshot have finished.

Implemented architecture

  • scripts/onboard.py performs inspection, URDF/MJCF/mesh normalization, stance calibration, policy adaptation, controller setup, task scaffolding, and native verification. Asset/physics/scaffolding operations are public Python APIs in mjrl.onboarding; policy adaptation is mjrl.adapter.adapt_policy, and controller setup is mjrl.controllers.setup_controller.
  • mjrl.controllers implements DLS IK with mocap targets, joint sliders, interpolated trajectories, differential/omni wheel mixing, and PD/CPG motion. The training and native runtimes share validated operator vocabulary/bindings.
  • mjrl.adapter wraps ONNX or TorchScript from explicit metadata, including named permutations, normalization, observation history, and per-joint scales. Interactive policies receive validated bindings; fixed actors expose no imaginary command channels.
  • Four templates define biped, quadruped, wheeled-biped and multipod training. Hash gates cover their algorithms and shared behavior dependencies. Robot onboarding creates only a literal tasks/<robot_id>/robot_spec.py in the task tree. Mixed wheel/leg targets and passive observed joints preserve their physical semantics in the versioned native export contract.
  • Native .app bundles contain models and dependencies, contracts, policies or trajectories, licenses, English/Chinese manuals, measured references, and a portable Python implementation. Python and third-party packages remain host requirements. The legacy Rust browser/board bundle is a distinct supported format; native hybrid contracts are not silently passed to a legacy reader.
  • Verification checks initial contact and limits, finite dynamics, root stability, effort saturation and requested physical response. It measures endpoint and body-frame mean/MAE responses, with an actuation-disabled counterexample. Velocity capability requires independent nonzero probes of each enabled axis; success while combining forward, sideways and yaw commands does not establish that each direction works on its own. Bundling fingerprints inputs, rejects missing gates, and reruns the packaged response before publication. The reader uses its own trusted schema.
  • Original exclusive robot assets/tasks were removed after shared mechanisms were extracted. Historical ignored exports were initially preserved, then removed during workspace cleanup: out/pre_platform_exports_20261104/ and out/bundle_example/jumper/. Training logs, failure reports and other user applications were retained. Scene dimensions are explicit nominal parameters.

Measured evidence

The final example collection is out/platform_release_20261104/. Each application has a checked Chinese manual. reference-checks.json records package replay.

Example Evidence Scope
mesh_viewer.app OBJ to MJCF, isolated portable replay Display only; no control claim
planar_arm.app IK endpoint error 5.14 micrometres; slider error 6.42e-10 rad; trajectory error 8.92e-7 rad Three separately verified modes
differential_drive.app At .35 m/s and .3 rad/s for 4 s: forward MAE .00799 m/s, yaw MAE .0284 rad/s; zero warnings Native wheel dynamics and WASD bindings
cpg_stance.app 10.4 s stance: .01086 rad tracking error, 8.30 mm translation, .04089 rad tilt change Stationary oscillatory stance, not walking
tier1_jit.app TorchScript adapter numerical error 0; final native joint error 1.17e-8 rad Synthetic fixed-target actor, not a trained gait
go1_example.app Seven 12 s native response probes plus full-range keyboard ramps; packaged references reproduce exactly Learned quadruped control on a flat floor
wheeled_biped_example.app Five isolated velocity/idle probes, full-range WASD, pad and release; eight-second .4 m/s packaged replay has .0450 m/s MAE and zero warnings Four position-controlled leg joints and two velocity-controlled wheels
g1_example.app Seven isolated native probes and full-range W/S/A/D/J/L with release; packaged .25 m/s replay averages .257 m/s with .0220 m/s MAE and zero warnings Learned 29-joint biped control on a flat floor

All four templates completed one PPO iteration on native CPU and Warp GPU using synthetic fixtures (four environments, 24 steps each): eight execution checks. A hybrid-wheel smoke checkpoint passed export and native replay parity but failed velocity tracking. That failure remains recorded and was not published as accepted locomotion. A separate passive-joint policy applied zero passive effort and matched checkpoint final position within 8.25e-8 rad.

The registered multipod_example and wheeled_biped_example add independent primitive-geometry models for the remaining families. Both passed native stance calibration: six supports carried the 5.14 kg multipod with 8.77 mm peak drift; two tires carried the 7.62 kg wheeled biped with 2.12 mm settling and no auxiliary supports. Neither hold produced self contacts or MuJoCo warnings. Their learning and policy-response results are measured separately from those static holds.

The selected wheeled-biped checkpoint completed 201 Warp updates across 1,024 environments (4,939,776 steps). Checkpoint 200 passed both stages with forward, reverse, left yaw, right yaw and idle commands. Its saved curriculum level is 1, with ranges of ±.91 m/s and ±.77 rad/s. Full-range WASD and pad tests confirmed these directions, a zero lateral channel, and immediate command release. The packaged policy matched its five references exactly. These are capabilities of the selected checkpoint; a later curriculum range may exceed this sample's wheel-speed limit and is not part of its published contract.

The multipod completed 1,000 Warp updates across 1,024 environments: 24,576,000 steps with no logged constraint overflow. Its final ONNX actor passed all 13 control probes, including the full-range keyboard directions. However, 11 probes failed physical support checks because one or both middle feet had no load during the final three seconds. Eight evaluated checkpoints failed to satisfy both stages, so there is no published multipod application. The report and diagnostic video in out/multipod_example/ preserve that distinction; no template or acceptance threshold was changed to turn this failure into a pass.

Go1 learning and selection

The licensed vendored Go1 model passed a two-second native stance hold using inertia-scaled gains: 16.1 mm maximum root displacement, .0562 rad maximum joint error, and 20.0% peak effort utilization, supported on all four feet.

A Warp/RTX 5080 run used 2,048 environments, 24 steps per PPO update and 1,000 updates: 49,152,000 environment steps. Checkpoint 900 was selected because its four feet remained loaded during the final three seconds of a 12-second idle probe. Checkpoint 999 tracked movement but unloaded the front-right foot. The selected checkpoint is:

logs/go1/go1_example/2026-11-04_18-51-49/model_900.pt

At a +.400 m/s command over 18 s on Warp, it averaged +.401 m/s with .022 m/s mean absolute forward error and zero resets. The initial checkpoint was nearly stationary with .400 m/s error. Native checkpoint and standalone ONNX tests covered forward, reverse, both lateral directions, both yaw directions, and idle, with no resets/warnings. ONNX worst translational MAE across those scenarios was .0309 m/s; worst yaw MAE was .0395 rad/s. The full evidence and hashes are in out/go1_example/training-summary.json; source provenance and repeatable commands are in assets/go1_example/README.md.

G1 learning and selection

The original G1 configuration completed 7,800 valid Warp updates across 1,024 environments: 191,692,800 environment steps. Rejected overflow runs and the incorrect early-resume promotion are excluded. The selected checkpoint is logs/g1/g1_example/2026-11-04_20-25-00/model_7796.pt.

It passed physics and control on all seven isolated 12-second native ONNX probes. Its published command ranges are ±.28 m/s forward/reverse, ±.14 m/s lateral and ±.32 rad/s yaw. Actual full-range keyboard tests had maximum per-axis MAE of .0231 m/s, .0375 m/s and .102 rad/s, no MuJoCo warnings and .0674 rad peak root tilt. Escape released commands; the measured post-release residuals were at most .00321 m/s, .00402 m/s and .0104 rad/s. All seven packaged references reproduced exactly. The shipped runtime was also executed from a fresh directory outside the checkout for its eight-second preview.

The gait uses short, low steps on the training plane. This does not establish obstacle clearance, robustness on other terrain or hardware readiness. The separate g1_compliant_example kept the same mechanical model and locked template but reduced hip/knee gains from 14 to 10 Hz and capped effort-derived action scales by available joint travel. It passed static calibration and learned forward movement earlier, but its 1,200-update policy failed lateral tracking and fell during a yaw probe. That trial is unpublished. Its task specification and source asset directory were removed so discovery no longer advertises it as a supported example. Both its failure and the accepted original configuration are preserved in their training summaries under out/.

Authorized locomotion template revision: regularization and history

The shared template now retains the six deployable actor channels but stacks four frames per term (oldest first, 20 ms control interval). The critic retains its single-frame privileged inputs. This changes actor input dimensions: old single-frame checkpoints must not be resumed or replayed against this template. Use fresh training runs; existing exported policy bundles retain their own observation contract and are not rewritten by this revision.

The revision adds mean position-joint HOME deviation (excluding wheel angles, three times stronger at rest), vertical linear and roll/pitch angular velocity costs, and contact-gated tangential support-speed cost. Slip cost is omitted for wheeled bipeds because wheel-center translation is legitimate rolling, not necessarily slip. A support-coverage cost penalizes missing contacts at rest and supports airborne for more than 0.5 seconds in motion, without requiring all feet to contact during a normal gait. Swing bonuses are paid only on landing using bounded air duration, not continuously while a foot remains raised. Both support terms are normalized by support count. These are morphology-independent starting weights, not a measured optimum or a prescribed gait/clearance guarantee.

Startup randomization adds base density scaling in [0.9, 1.1] (mass and inertia together via pseudo-inertia), and independent PD gain scales in [0.9, 1.1]. Existing COM offsets, friction, encoder bias and pushes remain. Play mode disables these randomizations. No vendored implementation was changed. The lock gains the PD randomization dependency; only the two revised shared implementation hashes are refreshed after behavioral review and regression testing.

Validation includes negative controls for permanently raised middle supports, hovering versus landing, airborne versus sliding feet, wheel-angle exclusion, and nonzero body damping. Native execution checks verify actual randomized mass, inertia and gains, four-frame observation ordering/reset, and exported history metadata. All four registered morphology examples completed one native CPU PPO update with four environments (96 transitions each). Multipod additionally completed one Warp/CUDA update with four environments (96 transitions), with finite losses and no logged contact/constraint overflow. Synthetic multipod and wheel models still emit their existing MjSpec option-attachment warnings. These are execution checks only: no convergence, 13-probe support acceptance, improved G1 gait, large-batch GPU capacity, or hardware result is claimed. The earlier failed multipod and short-step G1 evaluations above remain unchanged; full retraining, replay, and identical physics/control gates are still required.

Verification record and known limits

  • Baseline before refactoring: 1,214 passed, 24 skipped, two failures. Many removed tests belonged to the deleted exclusive tasks; shared mechanisms now use independent fixtures and meaningful negative controls.
  • Most recent complete suite after the endpoint/resource and mobility additions: 923 passed, one board-runtime test skipped. Current Rust controller core: 162 passed, one documentation example ignored. Browser tests compile current wasm and exercise deterministic ONNX reference vectors instead of scanning historical applications in out/.
  • Focused endpoint, packaging, adapter, template, and wheel-install regressions passed. The portable runtime rejects a bundle that weakens its own schema. Installed-wheel application creation and isolated replay were exercised. Velocity-controlled modes require measured body response on every enabled axis; spinning wheels on an immobilized chassis cannot satisfy that gate. A policy cannot receive nonzero commands on undeclared training ranges.
  • On this host, use env -u PYTHONPATH PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 when running pytest: unrelated ROS plugins otherwise interfere with discovery.
  • G1 provides a second real-morphology integration. Its calibrated stance passed after selecting coupled free-body inertia for gain sizing. Its initial Warp allocation was inadequate: a 64-environment smoke exited successfully despite constraint-overflow warnings, so that run is invalid. Explicit Warp allocation is now recorded/restored by train, replay and export. Overflow raises before the affected observations reach PPO. A 300-row allocation completed 29,491,200 training steps without overflow. Forward and reverse tracking improved, but lateral/yaw acceptance failed and prevented publication. A subsequent resume exposed startup episode ages being mistaken for earned curriculum evidence. That continuation was rejected. Restored runs now wait a fresh episode horizon before collecting promotion evidence; regression tests cover repeated loads as well as the first resume. The corrected continuations reached the accepted checkpoint described above. Details are in out/g1_example/training-summary.json.
  • The full suite and lint pass after the runtime changes; the eight accepted archives were refreshed and their references replayed. Actual board operation, Windows/macOS execution, and live Colab were not performed. The native Python format requires host runtime dependencies; it is not a bundled operating system or a hardware-ready board executable.