77 lines
4.0 KiB
Markdown
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.
|