Files
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

77 lines
4.0 KiB
Markdown

# Platform design
## One model, explicit contracts
Onboarding inspects input model files, mesh references, joint types and limits,
actuation, and optional policy metadata. It recommends a route using declared
intent and model evidence. The intake inventories upstream training configs
separately from unified policy metadata. Metadata extraction reads JSON and
YAML as data and Python as static syntax. It records provenance, conflicts
and unresolved expressions for review. A native verification report records
the model and compiled dependencies, controller inputs, and measured physics
and response separately.
Tier 1 converts the source actor to a validated ONNX graph and canonical layout
using explicit feature and joint order. Numerical parity tests check the
adapter against the source graph. Tier 2 binds a chosen deterministic
controller to named model elements. Both converge on the native verification
and packaging path.
## Locked training recipes
Tier 3 separates robot data from learning choices. A literal
`tasks/<robot_id>/robot_spec.py` declares the robot family, model and controls
paths, base body and height, contacts, and actuator calibrations. The registry
reads its literals without executing the module, and imports the selected
template only when building an environment.
The four recipes define body-frame velocity tracking with named proprioceptive
actor channels and a privileged critic. Channel widths follow the model's
selected joints and supports. Domain randomization changes support friction,
base center of mass, and encoder bias, and adds pushes. The curriculum
widens the command range after sustained tracking evidence, with the earned
level and evidence saved in each checkpoint. Wheeled bipeds use joint position
targets for legs and velocity targets for continuous wheel joints. Wheel
rotation is excluded from the position observation. Native policy layouts
record separate joint selections and the target kind per action channel.
The lock test protects family files and shared behavior dependencies. A
new calibration changes only the robot specification.
## One environment on two backends
mjlab's manager construction asks for a registered simulation class. Native
MuJoCo implements the same batched interface that MuJoCo Warp exposes, so
action, command, observation, reward, and PPO code is shared. Select the
backend before constructing the environment. Native copies a model per
environment and uses a thread pool. Warp batches state on the GPU. Backend
and environment count affect the experience collected in a run and are part
of any training report.
### Backend validation
Sharing the environment interface does not imply identical contact solutions
or learning curves. The example reports compare fixed-command checkpoint replay
on Warp and native MuJoCo, and compare native checkpoint replay with exported
ONNX. Each report records its own model, duration, command and noise setting.
These checks establish measured behavior for those runs, not bitwise equality
between simulators or equal training outcomes across different batch sizes.
Whether long-rollout state differences remain bounded, how they vary with
contact depth, and their effect on learning are not yet settled for this robot
collection. Settling these questions requires paired state measurements and
comparing learning curves with matched models, hyperparameters and seeds.
Warp records constraint/contact allocation alongside checkpoints and restores it
for replay and export. An overflow stops collection before the affected
observations reach PPO. A completed update with an overflow warning is not valid
training evidence.
## Packaging
The native app stores the model and referenced assets, exact mode artifacts,
verification evidence, manuals, and a Python controller entry point with its
host requirements. Model-only viewer apps verify compilation. Controlled modes
require passing reports for the exact model, controller, and bindings being
packaged. Legacy Rust artifacts are assembled by the existing bundle route.
See the [bundle format](../deploy/BUNDLE.md) for consumer details.