| --- |
| license: mit |
| pipeline_tag: reinforcement-learning |
| tags: |
| - robotics |
| - humanoid |
| - unitree-g1 |
| - isaac-lab |
| - rsl-rl |
| - ppo |
| - loco-manipulation |
| --- |
| |
| # HAMPER — G1 basket pickup policy |
|
|
| Pretrained weights for [HAMPER](https://github.com/WilliamHangXu/HAMPER): |
| a Unitree G1 humanoid that walks up to a basket on the floor, threads its |
| forearm through the handle, lifts it, and carries it away. Trained with PPO |
| (rsl_rl) in Isaac Lab through a staged curriculum, on a single RTX A6000. |
| |
| **These weights only work with the HAMPER repository at a matching commit.** |
| The checkpoint is half of the controller: the other half is the state machine in |
| `basket_pickup/commander.py`, which sequences approach → squat → thread → lift → |
| carry and presents the policy with the same commands and stage flag it trained |
| under. The observation and action layouts are frozen in `interface.py`; running |
| the network under any other layout produces garbage rather than an error. |
| Pinned stack: Isaac Sim 5.1.0, Isaac Lab v2.3.2, rsl_rl 3.1.2, torch 2.7.0+cu128 |
| (see `configs/versions.lock` in the repository). Scope: simulated whole-body |
| loco-manipulation with a hybrid PPO + state-machine controller; basket pose is |
| read from the simulator with synthetic noise — vision-based perception and |
| sim-to-real transfer are out of scope. SHA-256 hashes of these files are in the |
| repository's `results/manifest.json`. |
| |
| ## Files |
| |
| | File | What it is | Cumulative PPO updates | Checkpoint index | |
| |---|---|---:|---| |
| | `chain.pt` | **The final policy** — the full task | 9,500 (2,000 on the chain stage) | `model_9495` | |
| | `stage_thread.pt` | Parent of `chain.pt`: walk + carry + lift + thread | 7,500 | `model_7496` | |
| | `stage_lift.pt` | Parent of `stage_thread.pt`: walk + carry + lift | 5,500 | `model_5497` | |
| | `stage_carry.pt` | Parent of `stage_lift.pt`: walk + carry | 3,500 | `model_3498` | |
| | `generalist.pt` | Root of the chain: squat-capable walking with a commanded hand target; no basket | 2,000 | `model_1999` | |
| | `banks/standing_states.pt` (+ `.json`) | 5,000 harvested standing states used to initialize episodes | — | — | |
| | `banks/squat_states.pt` (+ `.json`) | 5,000 harvested squatting states used to initialize the lift and thread stages | — | — | |
| | `hero_video.mp4` | 60 s demo: full chain, threading close-up, robustness, failure case, ablation | — | — | |
|
|
| Checkpoint indices are rsl_rl iteration indices, which undercount cumulative |
| updates by one per resume; the update column is the number of PPO updates. The |
| staged pipeline additionally used a separate 1,500-update reach policy plus |
| state-bank harvesting to produce the banks above. |
| |
| Each checkpoint is an rsl_rl `OnPolicyRunner` save (actor, critic, optimizer |
| state). The banks are required for evaluating or fine-tuning any stage other |
| than plain walking: episodes of the carry, lift, thread and chain stages start |
| from bank states. |
|
|
| ## Results (`chain.pt` with the repository's commander) |
|
|
| All numbers use this one checkpoint (training seed 42); the baseline uses |
| three evaluation seeds of 500 episodes each; the 15 s, held-out and |
| training-conditions checks use one seed each. Strict full-chain success requires reaching the |
| carry phase, keeping the elevated basket to episode timeout, and moving it at |
| least 1.0 m after the carry begins. |
|
|
| - Strict, 10 s episodes (the training horizon): **1,216 of 1,500 — 81.1 %** |
| (95 % Wilson CI 79.0–83.0 %; per-seed 80.8 / 81.0 / 81.4 %). The shortfall |
| against the softer metric is the episode clock: carry distances have a median |
| of 1.4 m (10th percentile 0.87 m), and with 15 s episodes on the same spawn |
| distribution (one evaluation seed, 500 episodes) strict success is **99.4 %** |
| (median carry distance 3.2 m). |
| - Reached the carry phase and retained the elevated basket through timeout (no |
| distance requirement): 1,476 of 1,500 — 98.4 % (97.6–98.9 %; per-seed |
| 98.4 / 97.8 / 99.0 %). |
|
|
| We observed zero falls, zero basket knock-away events, and three transient |
| retention-latch loss events (0.002 per episode); an episode can re-establish |
| retention after a latch loss. |
|
|
| Per-stage evaluation — reached-phase/retention metrics, no carry-distance |
| requirement (strict full-chain numbers are above): |
|
|
| | | Walk | Carry | Lift | Thread | Full chain (reached-carry) | |
| |---|---|---|---|---|---| |
| | Success | 98.9 % | 95.9 % | 98.9 % | 82.2 % | 98.4 % | |
|
|
| Robustness (one policy, no retraining): mean success per tested handle opening |
| stayed at or above 95.5 % across 15–35 cm (lowest single evaluation seed: |
| 94.6 %, at 35 cm; trained on 25 cm) and was flat |
| across basket masses of 0.3–1.5 kg (trained on 0.4–1.0 kg). Among the |
| variables tested, basket-pose noise had the largest effect. The noise is |
| bounded uniform per Cartesian coordinate with the stated half-width (the policy |
| and the state machine share the observation model and bounds but draw |
| independent samples): above 97 % up to a 5 cm half-width, 23.5 % at 10 cm |
| (time-outs, not falls; sweep numbers use the reached-carry metric). On a spawn |
| distribution the state machine was never tuned on (basket 1–3 m away, ±90°, |
| one evaluation seed, 15 s episodes) the chain reaches 98.2 % strict success |
| over 500 episodes. |
|
|
| Things the numbers do not show: the 3 seeds are evaluation seeds of one trained |
| policy (retraining variance was not measured); the evaluation environment turns |
| off Isaac Lab's proprioceptive noise and pushes (under full training conditions |
| the chain scores 87.6 % strict / 100 % reached-carry over 500 episodes, one |
| evaluation seed); the state machine's constants were tuned |
| on the training spawn distribution. The repository README has the full |
| discussion, sweep plots, and ablations. |
|
|
| ## How to run |
|
|
| Set up the repository as described in its README (Isaac Sim, Isaac Lab v2.3.2, |
| `uv pip install -e source/basket_pickup`), then from the repository root: |
|
|
| ```bash |
| hf download WillXH/HAMPER --local-dir weights |
| cp weights/banks/* banks/ # the stage evaluations need the state banks |
| |
| # full task, 200 episodes, records a video next to the checkpoint |
| python scripts/eval_stage.py --checkpoint weights/chain.pt --stage D_CHAIN |
| # individual stages |
| python scripts/eval_stage.py --checkpoint weights/chain.pt --stage C_THREAD # or B_LIFT, A_CARRY, LOCO |
| ``` |
|
|
| To fine-tune from a stage checkpoint, rsl_rl expects it inside a run directory |
| under `logs/rsl_rl/basket_pickup/`: |
| |
| ```bash |
| mkdir -p logs/rsl_rl/basket_pickup/hf_stage_thread |
| cp weights/stage_thread.pt logs/rsl_rl/basket_pickup/hf_stage_thread/model_7496.pt |
| python scripts/rsl_rl/train.py --task Basket-Pickup-v0 --headless --num_envs 4096 \ |
| --resume --load_run hf_stage_thread --checkpoint model_7496.pt --max_iterations 2000 --run_name my_chain |
| ``` |
| |
| ## License |
| |
| Weights: MIT. The G1 robot description and Isaac Lab are BSD-3-Clause |
| (NVIDIA / Unitree); rsl_rl is BSD-3-Clause. |
| |
