How xbyyh/go2-low-friction-locomotion-benchmark works
1. What this repository is
This repo is not a full standalone RL stack; it is an experiment overlay for the original Unitree RL / MuJoCo locomotion project. Its main purpose is to compare a baseline Go2 policy against a slippery-trained robust policy under flat and low-friction terrain.
2. Core architectural boundary
The real training/runtime code lives in the upstream Unitree RL repository. This repo contributes a small set of replacement files that alter:
- environment configuration,
- evaluation command generation,
- evaluation analysis/plotting,
- and command-set definitions.
So the boundary is: upstream RL framework provides training/eval engine; this repo provides task-specific benchmark logic and outputs.
3. Configuration subsystem
The key config files are:
- velocity_env_cfg.py
- env_cfgs.py
- __init__.py
These adapt the Go2 velocity task configuration. From the README, they are meant to be copied into the upstream src/tasks/velocity/... tree. This is where flat vs slippery terrain behavior, friction randomization, and Go2-specific environment variants are defined.
4. Command/evaluation input subsystem
go2_eval_cmd_set_v1.json is the fixed evaluation command schedule. It is the input that drives the benchmark’s repeated command sequences, so both policies are tested on the same command stream for fair comparison. This is an important data boundary: command set in, evaluation trajectories out.
5. Evaluation runner
eval_fixed_cmd.py appears to be the script that executes the trained policy against the fixed command set and logs tracking behavior. The README shows it is used for:
- velocity tracking at multiple linear speeds (vx)
- angular tracking at multiple yaw speeds (wz)
- and the extreme yaw reversal stress test.
Architecturally, this is the stage that sits between trained policy checkpoints and analysis plots.
6. Analysis and plotting subsystem
analyze_and_plot_eval.py and comprehensive_plot.py are post-processing utilities. They consume evaluation logs and produce the figures shown in the README:
- per-scenario tracking plots,
- mean/steady-state error comparisons,
- and summary charts such as comprehensive_error_comparison.png.
This is the repo’s reporting layer: it turns raw eval traces into benchmark evidence.
7. Experiment branches: baseline vs robust
The repository stores two parallel experiment tracks:
- baseline_checkpoint and baseline/Unitree_Go2_*
- slippery1.0_checkpoint and slippery1.0plot/Unitree_Go2_*
These represent the two policies being compared. The baseline is trained on flat/default conditions, while the robust policy is trained with slippery/friction-randomized terrain. The folder names make the comparison axis explicit: policy variant × terrain type.
8. Checkpoint/artifact layout
Each checkpoint directory contains:
- model_4800.pt — the selected PyTorch model checkpoint,
- policy.onnx — exported inference model,
- params/agent.yaml and params/env.yaml — run metadata/config snapshot,
- TensorBoard event files — training curves,
- git/unitree_rl_mjlab.diff — code diff against upstream.
These artifacts show the repo is optimized for reproducibility and comparison, not for a generic runtime service.
9. Training-to-evaluation data flow
The lifecycle is:
1. train PPO policy in the upstream Unitree RL framework,
2. save checkpoint near peak performance (around 4800 iterations per README),
3. export or load the checkpoint for evaluation,
4. run fixed-command tests on flat/slippery terrains,
5. post-process logs into plots and summary metrics.
That flow is the main architecture diagram you’d want to draw.
10. Training setup and external dependencies
The project depends on the upstream PPO-based locomotion controller, MuJoCo simulation, and the Unitree Go2 task definition. The README’s training commands indicate GPU-based training via CUDA_VISIBLE_DEVICES, and parallel simulation environments (--env.scene.num_envs 256). So the runtime is a simulation-first RL workload, not an on-robot deployment stack.
11. Repository organization as deliverables
The top-level files are mostly “benchmark deliverables”:
- scripts that replace upstream ones,
- trained checkpoints,
- generated plots,
- and the README narrative comparing performance.
In diagram terms, the repo contributes two main outputs: trained policy artifacts and evaluation visualizations.
12. Practical architecture summary
A concise diagram would show:
- Upstream Unitree RL training engine in the center,
- Go2 env/config overrides feeding it,
- fixed command JSON feeding evaluation,
- trained checkpoints flowing into evaluation,
- plotting scripts consuming logs and producing benchmark figures,
- and two parallel branches: baseline vs slippery-trained robust.
Main entry points: comprehensive_plot.py Plotter · eval_fixed_cmd.py Eval runner · README.md README · env_cfgs.py Env configs
Components 16
Benchmark overlay
Repository files that adapt the upstream Unitree RL Go2 task for the low-friction benchmark.
- README · Benchmark description, setup, and comparison narrative.
README.md - Task init · Package entry used when the upstream task tree imports these overrides.
__init__.py - Env configs · Go2 environment configuration variants and benchmark-specific overrides.
env_cfgs.py - Velocity cfg · Velocity-task configuration tuned for flat vs slippery terrain behavior.
velocity_env_cfg.py - Command set · Fixed command schedule used to compare policies under identical motion sequences.
go2_eval_cmd_set_v1.json - Eval runner · Runs trained policies against the fixed command set and collects tracking logs.
eval_fixed_cmd.py - Analysis · Aggregates evaluation traces into summary metrics and comparisons.
analyze_and_plot_eval.py - Plotter · Builds comprehensive benchmark figures from analysis outputs.
comprehensive_plot.py
Policy artifacts
Saved checkpoints and metadata for the baseline and slippery-trained policies.
- Baseline ckpt · Checkpoint bundle for the flat/default policy variant.
baseline_checkpoint - Slippery ckpt · Checkpoint bundle for the friction-randomized robust policy variant.
slippery1.0_checkpoint
Evaluation outputs
Generated plots and comparison figures produced from fixed-command evaluation.
- Baseline flat · Baseline policy results on flat terrain.
baseline/Unitree_Go2_Flat - Baseline slip · Baseline policy results on slippery terrain.
baseline/Unitree_Go2_Slippery - Robust flat · Slippery-trained policy results on flat terrain.
slippery1.0plot/Unitree_Go2_Flat - Robust slip · Slippery-trained policy results on slippery terrain.
slippery1.0plot/Unitree_Go2_Slippery
Other components
- Unitree RL · Upstream PPO-based locomotion training and simulation engine.
- MuJoCo · Physics simulation backend used by the locomotion benchmark.
Connections 22
- README → Env configs: documents · Explains how the override configs are used in the upstream tree.
- README → Command set: defines · Describes the fixed evaluation command schedule.
- README → Eval runner: invokes · Shows how to run fixed-command evaluation for both policies.
- README → Analysis: reports · Describes the post-processing and comparison workflow.
- Env configs → Velocity cfg: specializes · Task-level environment variants build on the velocity task config.
- Task init → Env configs: exports · Package entry makes the override modules importable.
- Velocity cfg → Unitree RL: overrides · Replacement configuration is copied into the upstream framework.
- Env configs → Unitree RL: overrides · Benchmark-specific environment variants plug into the upstream task code.
- Unitree RL → MuJoCo: simulates on · The locomotion controller runs inside MuJoCo.
- Command set → Eval runner: feeds · Fixed commands drive the evaluation loop.
- Baseline ckpt → Eval runner: evaluated by · Baseline policy checkpoint is loaded for benchmarking.
- Slippery ckpt → Eval runner: evaluated by · Robust policy checkpoint is loaded for benchmarking.
- Eval runner → Analysis: logs to · Evaluation traces are summarized into metrics.
- Analysis → Plotter: feeds · Summary statistics are turned into comparison figures.
- Baseline ckpt → Baseline flat: produces · Baseline checkpoint underlies the flat-terrain result set.
- Baseline ckpt → Baseline slip: produces · Baseline checkpoint underlies the slippery-terrain result set.
- Slippery ckpt → Robust flat: produces · Robust checkpoint underlies the flat-terrain result set.
- Slippery ckpt → Robust slip: produces · Robust checkpoint underlies the slippery-terrain result set.
- Plotter → Baseline flat: compares · Uses the baseline flat result in summary plots.
- Plotter → Baseline slip: compares · Uses the baseline slippery result in summary plots.
- Plotter → Robust flat: compares · Uses the robust flat result in summary plots.
- Plotter → Robust slip: compares · Uses the robust slippery result in summary plots.