How robfiras/loco-mujoco works
Project Type and Purpose
• LocoMuJoCo is an open-source Python library and benchmark for imitation and reinforcement learning over MuJoCo/MJX-based locomotion environments.
• It provides:
• A large collection of simulated environments (humanoids, quadrupeds, musculoskeletal models)
• Datasets (AMASS, LAFAN1, native) and retargeting via SMPL
• Clean JAX implementations of algorithms (PPO, GAIL, AMP, DeepMimic)
• Modular “pluggable” components (observations, rewards, domain randomizers, etc.)
• Gymnasium API wrappers and utilities for logging, metrics, video
High-Level File Structure & Architectural Patterns
• Top-level package “loco_mujoco”: core modules, environments, datasets, algorithms, task_factories, trajectory, smpl, utils
• Modular design (plugin architecture): each component (e.g., control_functions, reward, terrain) is a separate subpackage under core
• Single-file JAX algorithms under loco_mujoco/algorithms
• TaskFactory orchestrates environment + dataset + training loop
• Uses Python packaging (setup.py, pyproject.toml), CI (GitHub Actions), ReadTheDocs for docs
Main Components
a. Simulation & Environment Layer
• MuJoCo Engine (C library) & MJX runner (parallel)
• loco_mujoco/core: base classes, wrappers (gymnasium, mjx), control, observations, reward, terminal, terrain, visuals
• loco_mujoco/environments: concrete robot environments (humanoids/quadrupeds), MuJoCo/XML models in loco_mujoco/models
b. Dataset & Retargeting Layer
• loco_mujoco/datasets: data generation utilities, dataset loaders
• loco_mujoco/smpl: SMPL parsing, model generation, robot-to-robot retargeting
c. TaskFactory / API Layer
• loco_mujoco/task_factories: ImitationFactory, RLFactory – encapsulate env+dataset+config → Gymnasium-compatible environment
d. Algorithm Layer
• loco_mujoco/algorithms: PPO, GAIL, AMP, DeepMimic – JAX functions taking batched observations, returning actions
• Combined training+env.step in a single JIT-compiled function
e. Trajectory & Metric Layer
• loco_mujoco/trajectory: data classes, handlers
• loco_mujoco/utils/metrics: DTW, Fréchet distance, running stats
f. Utility Layer
• loco_mujoco/utils: dataset caching, logging, video recording, environment utilities
• CLI tools (loco-mujoco-set-all-caches, loco-mujoco-myomodel-init)
g. Examples / Tutorials / Tests
• examples/: quickstarts, training_examples, tutorials
• docs/: Sphinx sources
• tests/: unit and integration tests
Relationships & Data Flow
• Algorithm → Env: action tensor flows from JAX algorithm to environment wrapper → MuJoCo/MJX
• Env → Algorithm: observations, rewards, done flags stream back
• Dataset → Env (imitation): trajectories fed into environment for guidance
• TaskFactory ties Dataset + Env + Algorithm config into a single training pipeline
• Utils (logging, video, metrics) hook into the training loop for monitoring
Architectural Patterns & Principles
• Plugin architecture: each “core” submodule can be swapped (e.g., different reward or domain randomizer)
• JIT-compiled end-to-end train+simulate loop for performance
• Clear separation of concerns: simulation core, data loading, algorithm logic, utilities
• Use of dataclasses and configuration files (YAML) to drive extensibility