Huy-Quang-Dao/instantTrack

What it does

InstantTrack is a research training codebase for whole-body motion tracking on the simulated Unitree G1 humanoid. It builds on SuperMimic's approach — a differentiable world model with policy gradients backpropagated through imagined rollouts — and adds training-loop engineering from InstantMimic plus a few algorithmic changes. Every change is exposed as a flag, so the baseline and each increment share the same simulator, MDP, reward, termination, domain randomization, and evaluator.

The headline configuration, v1.2, trains one policy for all 40 LAFAN1 clips and reaches the evaluation target (normalized return ≥ 0.82 with 0/40 failed clips, held for three consecutive checkpoints) in a mean of 0.12 h across five seeds on one RTX 5090, versus 0.55 h for the authors' SuperMimic + EMA reimplementation as reported in the README. The claimed 4.7× is against that reimplementation on the same hardware, not against the SuperMimic paper's H100 numbers.

The intended audience is robotics RL researchers and engineers who want to train, ablate, or reproduce humanoid tracking policies. It is not a deployment stack: there is no sim-to-real experiment and no larger motion set in scope.

Setup and first run

Requirements are Linux x86_64, an NVIDIA GPU with a CUDA 12.8 driver (tested on an RTX 5090), uv, git, and curl; ffmpeg is only needed for video rendering. Plan for about 10 GB of disk for the environment and data, plus roughly 2 GB per 0.75 h run of checkpoints.

git clone https://github.com/Huy-Quang-Dao/instantTrack.git
cd instantTrack
uv sync                          # mjlab, MuJoCo Warp, Warp, torch 2.9.0 (CUDA 12.8)
tools/download_data.sh           # LAFAN1 G1 retargets (40 clips) + G1 description -> data/
uv run python tools/test_env.py  # sanity check: FK vs simulator, state round-trip, playback

The data script pulls the G1-retargeted LAFAN1 clips and robot description from a Hugging Face dataset and converts the URDF to MJCF; the motion data is not redistributed in the repository details.

Then train with the main preset and evaluate its checkpoints:

scripts/train.sh instanttrack it_s0 --seed 0 --max_hours 0.75

This runs python -m instanttrack.train with the v1.2 flags and then tools/eval_batch.py. Per-run output lands in logs/it_s0/: train_log.csv, checkpoints every 3 minutes and every 2000 iterations, args.json, and stdout.log. To reproduce the comparison tables, scripts/reproduce_main.sh runs SuperMimic + EMA and InstantTrack over three seeds at 0.75 h (about 5 h), and tools/make_report.py rebuilds the tables and figures from results/runs/ reproduction steps.

To train directly instead of via the script:

uv run python -m instanttrack.train --log_dir logs/my_run --seed 0 --max_hours 0.75 \
  --pi_ema 0.995 --no_sync --fused_adam --fused_rot --compile_more --lr 4e-4 --wm_batches 5 \
  --wm_hidden 1024,1024,1024 --fail_reset 0.3 --contact_reward 0.25 --ref_residual 1.0 \
  --muon --cuda_graph --batch_goal_enc --enc_hidden 1024,512,256 --dec_hidden 1024,512,256

--cuda_graph requires --no_sync --fused_adam and a CUDA GPU; it captures the two update phases after the world-model-only warm-up, and the few seconds of capture count toward training time training details.

Practical constraints

• Hardware and platform. Training is measured on a single dedicated RTX 5090 with 4096 parallel environments; a second process on the same GPU slows the loop by 1.5–2×. Linux x86_64 only.
• Timing reproducibility. Checkpoints are 3 minutes apart, so reported times are quantized to 0.05 h, and GPU runs are not bit-reproducible; re-running the same seed moved one configuration from 0.30 h to 0.34 h.
• Benchmark scope. Only the Unitree G1 in simulation on the 40 LAFAN1 clips, evaluated without domain randomization or pushes. No sim-to-real validation.
• Known weaknesses. Global root drift stays larger than the SuperMimic + EMA baseline (52 cm for v1.2 vs 49–54 cm at 1.5 h), hard clips can regress after first meeting the target (v1.2 seed 4 on jumps1_subject2), and the contact reward trades about 0.03 h of time-to-target and ~0.007 return for better contact metrics.
• Muon under CUDA graphs. Muon's learning rate is a Python float fixed at graph capture, so it does not follow the cosine schedule; in the v1.2 runs it was at most 8% above schedule.
• Licensing. Code is MIT. LAFAN1 motions are CC BY-NC-ND 4.0 and are not redistributed; derived GIFs, videos, and checkpoints are for non-commercial research and illustration only, outside the MIT license attribution.

HotRepo's take

There is no daily-ranking record or discussion thread for this repository in the HotRepo data; it appears only on the new-project list for Python on 2026-11-03, when it reported 13 stars gained over roughly five hours and moved from 100 to 113 stars. That is a short window, enough to note early interest but not to characterize a trend. What stands out instead is the documentation: the README publishes per-seed time-to-target, an ablation ladder, a list of changes that did not help, per-run logs, and an explicit warning that the baseline is the authors' own SuperMimic reimplementation and that EMA — not InstantTrack alone — accounts for much of the early speedup. For readers evaluating the speed claims, that framing is more informative than the star count.