mjlab-piplus

Pi+ humanoid experiments using mjlab (MuJoCo + RSL-RL + PPO). These are mainly personal experiments, if you want to see more with what we do with the PI+ humanoid robot, and many other cool things, check out the Hamburg bit-bots RoboCup team.

Setup

uv sync
uv run wandb login   # required for training

Experiments

Task	Description
Mjlab-Piplus-Upright	Baseline: stand upright on flat terrain
Mjlab-Piplus-NonInertial	Sinusoidal forces on root body simulating platform acceleration
Mjlab-Piplus-Platform	Physical 3 m × 3 m mocap platform with roll, pitch, heave (boat motion)
Mjlab-Piplus-Locomotion	Velocity-tracked walking on flat terrain (legs only)
Mjlab-Piplus-Locomotion-Arms	Same, with arms actuated
Mjlab-Piplus-Ball	Balance on a large free-rolling ball (0.45 m radius)
Mjlab-Piplus-Ball-Arms	Same, with arms actuated
Mjlab-Piplus-Ball-Small	Single-leg balance on a football; sim2real setup
Mjlab-Piplus-Ball-Small-Turf	Same, on astroturf (soft two-plane terrain)

Train

bash scripts/train.sh                          # interactive task selection menu
bash scripts/train.sh Mjlab-Piplus-Platform    # skip menu
bash scripts/train.sh --cpu                    # CPU mode, 64 envs
bash scripts/train.sh --tmux                   # wrap in tmux session mjlab-train
bash scripts/train.sh --num-envs 2048          # custom env count (reduce if OOM)

Runs 4096 envs on GPU by default, logs to wandb under the task name.

Play

uv run mjx play                                # interactive task + run selection
uv run mjx --task Mjlab-Piplus-Platform play   # skip menu

Or directly:

uv run play Mjlab-Piplus-Platform \
  --checkpoint-file logs/rsl_rl/piplus_platform/<run>/model_N.pt \
  --viewer viser --num-envs 1

Manage runs

uv run mjx runs                                # list runs with iteration count and age
uv run mjx clean                               # prune old checkpoints (keep every 5th)
uv run mjx clean --dry-run                     # preview what would be deleted

Repo structure

src/mjlab_piplus/
  robot/                  Pi+ MJCF + constants (actuators, collision presets)
  tasks/
    upright/              Mjlab-Piplus-Upright
    noninertial/          Mjlab-Piplus-NonInertial
    platform/             Mjlab-Piplus-Platform
    locomotion/           Mjlab-Piplus-Locomotion
    locomotion_arms/      Mjlab-Piplus-Locomotion-Arms
    ball/                 Mjlab-Piplus-Ball
    ball_arms/            Mjlab-Piplus-Ball-Arms
    ball_small/           Mjlab-Piplus-Ball-Small, Mjlab-Piplus-Ball-Small-Turf
  terrains/               Custom terrains (astroturf)
scripts/
  train.sh                GPU training launcher with wandb + optional tmux
logs/rsl_rl/              Checkpoints (gitignored)
docs/                     Per-experiment design notes

See AGENTS.md or CLAUDE.md for architecture details and notes relevant to further development.