Metadata-Version: 2.3
Name: amp-unilab
Version: 0.1.0
Summary: AMP_mjlab G1 locomotion semantics on the UniLab Manager-Based runtime
License: BSD-3-Clause
Requires-Dist: unilab[mujoco,mjwarp]==1.3.1
Requires-Dist: unilab-rl==1.3.0
Requires-Dist: mujoco==3.11.0
Requires-Dist: torch>=2.6,<2.9
Requires-Dist: numpy>=1.26,<3
Requires-Dist: scipy>=1.14,<2
Requires-Dist: numba>=0.61,<0.68
Requires-Dist: onnx>=1.16
Requires-Dist: onnxruntime>=1.19
Requires-Python: >=3.11, <3.14
Description-Content-Type: text/markdown

# AMP_unilab

[中文说明](README.zh-CN.md)

AMP G1 locomotion/recovery training migrated from `AMP_mjlab` (source revision
`6c7a2947`) onto the UniLab Manager-Based runtime. UniLab and unilab-rl are
external pinned dependencies; this package owns only task configuration, AMP
public-runtime bridging, and the vendored AMP-capable RSL-RL runner.

## Tasks

- `Unitree-G1-AMP-Flat` (MuJoCo Warp backend by default; CPU mjbatch remains
  available with `--sim mujoco`)
- 29 controlled joints
- actor observation: 96 terms × 4 history = 384
- critic observation: 216 terms × 4 history = 864
- AMP discriminator state: 13 bodies × 15 = 195; transitions use 390 inputs
- 20 s episode, 50 Hz physics, 25 Hz control, expert clips: all 18 walk/run
  and recovery NPZ files

UniLab discovers the task through the `unilab.tasks` entry point:

```bash
amp-list-envs
amp-train --task Unitree-G1-AMP-Flat --num-envs 4096
amp-export --checkpoint runs/g1_amp_unilab/model_final.pt --output policy.onnx
amp-play --checkpoint runs/g1_amp_unilab/model_final.pt --steps 1000
```

The source G1 AMP PPO/AMP hyperparameters are preserved in
`src/amp_unilab/training/config.py`: 24 steps/env, four mini-batches, adaptive
learning rate, 0.75 task-reward lerp, 0.1 AMP reward coefficient, 100k AMP
replay buffer, `[1024,512,256]` discriminator, and `[512,256,128]` actor/critic
MLPs with empirical observation normalization.

## Robot assets

The G1 structural XML is repository-owned at
`src/amp_unilab/assets/robots/g1/g1.xml`; the flat scene and task keyframe are in
the adjacent `scene_flat.xml`. Mesh STLs stay out of git. At configuration time,
the package writes a content-addressed runtime XML whose `meshdir` points to
UniLab's registered asset hub.

## Commands

```bash
uv sync
make check        # formatting and lint
make test         # fast registry/config/motion tests
make test-all     # also constructs MuJoCo and runs a one-iteration CPU AMP update
make build
```

## Migration status and known differences

The objective is behavioral parity, but this first migration is deliberately
explicit about what differs instead of hiding it behind compatibility seams.

### Aligned or closely bridged

- Flat G1 task, command model, control rate, action ordering and exact scales
- actor/critic term composition and dimensionality
- AMP state construction and all 18 expert clips
- expert transition sampling and AMP discriminator/optimizer behavior
- motion reset sampling from walk/run groups, with recovery clips selected for
  the source's 40% delayed-reset subset
- the repository-owned G1 structure, task keyframe, Unitree PD gains, armature,
  and torque-speed curve are control-step equivalents of AMP_mjlab's
  `UnitreeActuator` semantics
- play mode disables observation noise and interval pushes and samples recovery
  resets for all environments

### Backend difference

The default MuJoCo Warp path omits `push_robot` because UniLab's interval
root-velocity-delta capability is unavailable on that backend. The task keeps
this difference explicit instead of probing backend internals; use `--sim
mujoco` when interval velocity pushes are required.

### Current differences

- History remains UniLab's term-major representation. AMP_mjlab uses
  time-major `[T-3,...,T]`; UniLab's public observation manager currently
  concatenates history term-major.
- AMP_mjlab evaluates its actuator model on every physics substep. UniLab's
  public per-substep action feedback currently cannot refresh tracked body
  state with MuJoCo `implicitfast`, so AMP_unilab preserves the source
  integrator and evaluates the torque-speed/friction model once per control
  step.
- The source `DelayedTerminationManager` (40% of environments, up to 250 control
  steps) is not installed because replacing a manager is outside UniLab's
  declared manager lifecycle. Consequently the delayed-root-height masking and
  3.5× delayed reward path cannot be reproduced yet.
- Startup domain randomization for foot friction, encoder bias, and base COM
  offset is not enabled; the corresponding UniLab MuJoCo capability bridge is
  not part of this task package.
- Foot slip and self-collision penalties require contact force/history
  capabilities and are not present.
- The three-stage velocity command curriculum and rough terrain/height scan are
  not present. Only Flat is exposed.

Training results before closing these gaps are not expected to be numerically
identical to AMP_mjlab. Do not treat this as a benchmark-compatible release.

## License

Task files follow the repository's BSD-3-Clause licensing. Vendored
`src/amp_unilab/vendor/rsl_rl` retains its original upstream notices and BSD-3-Clause
license.
