# robfiras/loco-mujoco architecture

> Architecture diagram of the GitHub repository robfiras/loco-mujoco, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/robfiras/loco-mujoco
- Repository: https://github.com/robfiras/loco-mujoco

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    MuJoCo["MuJoCo Engine (C)"]:::external
    MJX["MJX Runner"]:::external
    JAX["JAX"]:::external
    Gymnasium["Gymnasium API"]:::external
    HF["HuggingFace Datasets"]:::external

    %% Simulation & Environment Layer
    subgraph "Simulation & Environment Layer"
        direction TB
        Core["Simulation & Env Core"]:::simcore
        WrappersGym["Gymnasium Wrapper"]:::simcore
        WrappersMJX["MJX Wrapper"]:::simcore
        Control["Control Functions Plugin"]:::simcore
        DomainRand["Domain Randomizers Plugin"]:::simcore
        Observations["Observation Modules"]:::simcore
        Reward["Reward Modules"]:::simcore
        Terminal["Terminal State Handlers"]:::simcore
        Terrain["Terrain Modules"]:::simcore
        VisualsScene["Scene Visuals"]:::simcore
        VisualsVideo["Video Recorder"]:::simcore
        Envs["Environment Definitions"]:::simcore
        Models["MuJoCo/XML Models & Assets"]:::simcore
    end

    %% Dataset & Retargeting Layer
    subgraph "Dataset & Retargeting Layer"
        direction TB
        Datasets["Dataset Loaders & Generation"]:::data
        SMPLParser["SMPL Parser"]:::data
        Retarget["SMPL Retargeting"]:::data
        HF
    end

    %% TaskFactory / API Layer
    subgraph "TaskFactory / API Layer"
        direction TB
        ImitationFactory["ImitationFactory"]:::api
        RLFactory["RLFactory"]:::api
        ConfigYAML["Config (YAML)"]:::api
    end

    %% Algorithm Layer
    subgraph "Algorithm Layer"
        direction TB
        PPO["PPO_JAX"]:::algo
        GAIL["GAIL_JAX"]:::algo
        AMP["AMP_JAX"]:::algo
        DeepMimic["DeepMimic_JAX"]:::algo
        AlgoCommon["Shared Algo Utils"]:::algo
        JAX
    end

    %% Trajectory & Metric Layer
    subgraph "Trajectory & Metric Layer"
        direction TB
        TrajData["Trajectory Dataclasses"]:::metric
        TrajHandler["Trajectory Handler"]:::metric
        Metrics["Metrics Utilities"]:::metric
    end

    %% Utility Layer
    subgraph "Utility Layer"
        direction TB
        DatasetCache["Dataset Caching"]:::util
        Logging["Logging Utility"]:::util
        VideoUtil["Video Utility"]:::util
        MyoInit["MyoModel Init CLI"]:::util
    end

    %% Examples / Docs / Tests
    subgraph "Examples / Docs / Tests"
        direction TB
        Examples["Examples / Tutorials"]:::external
        Docs["Documentation Source"]:::external
        Tests["Tests & CI"]:::external
    end

    %% Data Flows
    PPO -->|"action tensor"| WrappersGym
    GAIL -->|"action tensor"| WrappersGym
    AMP -->|"action tensor"| WrappersGym
    DeepMimic -->|"action tensor"| WrappersGym
    WrappersGym -->|"/step"| Core
    Core -->|"obs, reward, done"| PPO
    Envs -->|"XML models"| Core
    Models --> Envs
    Datasets -->|"trajectory batch"| ImitationFactory
    ImitationFactory --> Envs
    ConfigYAML --> ImitationFactory
    ConfigYAML --> RLFactory
    RLFactory --> PPO
    AlgoCommon --> PPO
    AlgoCommon --> GAIL
    AlgoCommon --> AMP
    AlgoCommon --> DeepMimic
    TrajData --> Metrics
    TrajHandler --> Metrics
    Metrics --> Logging
    Logging --> Examples
    VideoUtil --> Examples
    DatasetCache --> Datasets
    SMPLParser --> Retarget
    Retarget --> Envs
    Gymnasium --> WrappersGym
    MJX --> WrappersMJX
    WrappersMJX --> Core

    %% Click Events
    click Core "https://github.com/robfiras/loco-mujoco/tree/master/loco_mujoco/core"
    click WrappersGym "https://github.com/robfiras/loco-mujoco/blob/master/loco_mujoco/core/wrappers/gymnasium.py"
    click WrappersMJX "https://github.com/robfiras/loco-mujoco/blob/master/loco_mujoco/core/wrappers/mjx.py"
    click Control "https://github.com/robfiras/loco-mujoco/tree/master/loco_mujoco/core/control_functions"
    click DomainRand "https://github.com/robfiras/loco-mujoco/tree/master/loco_mujoco/core/domain_randomizer"
    click Observations "https://github.com/robfiras/loco-mujoco/tree/master/loco_mujoco/core/observations"
    click Reward "https://github.com/robfiras/loco-mujoco/tree/master/loco_mujoco/core/reward"
    click Terminal "https://github.com/robfiras/loco-mujoco/tree/master/loco_mujoco/core/terminal_state_handler"
    click Terrain "https://github.com/robfiras/loco-mujoco/tree/master/loco_mujoco/core/terrain"
    click VisualsScene "https://github.com/robfiras/loco-mujoco/blob/master/loco_mujoco/core/visuals/scene.py"
    click VisualsVideo "https://github.com/robfiras/loco-mujoco/blob/master/loco_mujoco/core/visuals/video_recorder.py"
    click Envs "https://github.com/robfiras/loco-mujoco/tree/master/loco_mujoco/environments"
    click Models "https://github.com/robfiras/loco-mujoco/tree/master/loco_mujoco/models"
    click Datasets "https://github.com/robfiras/loco-mujoco/tree/master/loco_mujoco/datasets"
    click SMPLParser "https://github.com/robfiras/loco-mujoco/blob/master/loco_mujoco/smpl/parser.py"
    click Retarget "https://github.com/robfiras/loco-mujoco/blob/master/loco_mujoco/smpl/retargeting.py"
    click ImitationFactory "https://github.com/robfiras/loco-mujoco/blob/master/loco_mujoco/task_factories/imitation_factory.py"
    click RLFactory "https://github.com/robfiras/loco-mujoco/blob/master/loco_mujoco/task_factories/rl_factory.py"
    click PPO "https://github.com/robfiras/loco-mujoco/blob/master/loco_mujoco/algorithms/ppo_jax.py"
    click GAIL "https://github.com/robfiras/loco-mujoco/blob/master/loco_mujoco/algorithms/gail_jax.py"
    click AMP "https://github.com/robfiras/loco-mujoco/blob/master/loco_mujoco/algorithms/amp_jax.py"
    click DeepMimic "https://github.com/robfiras/loco-mujoco/blob/master/loco_mujoco/algorithms/deepmimic_jax.py"
    click AlgoCommon "https://github.com/robfiras/loco-mujoco/tree/master/loco_mujoco/algorithms/common"
    click TrajData "https://github.com/robfiras/loco-mujoco/blob/master/loco_mujoco/trajectory/dataclasses.py"
    click TrajHandler "https://github.com/robfiras/loco-mujoco/blob/master/loco_mujoco/trajectory/handler.py"
    click Metrics "https://github.com/robfiras/loco-mujoco/blob/master/loco_mujoco/utils/metrics.py"
    click Logging "https://github.com/robfiras/loco-mujoco/blob/master/loco_mujoco/utils/logging.py"
    click VideoUtil "https://github.com/robfiras/loco-mujoco/blob/master/loco_mujoco/utils/video.py"
    click DatasetCache "https://github.com/robfiras/loco-mujoco/blob/master/loco_mujoco/utils/dataset.py"
    click MyoInit "https://github.com/robfiras/loco-mujoco/blob/master/loco_mujoco/utils/myomodel_init.py"
    click Examples "https://github.com/robfiras/loco-mujoco/tree/master/examples/"
    click Docs "https://github.com/robfiras/loco-mujoco/tree/master/docs/source/"
    click Tests "https://github.com/robfiras/loco-mujoco/tree/master/tests/"

    %% Styles
    classDef simcore fill:#d0e7ff,stroke:#005b99,stroke-width:1px
    classDef data fill:#d0ffd6,stroke:#007a29,stroke-width:1px
    classDef api fill:#fff2cc,stroke:#b37f00,stroke-width:1px
    classDef algo fill:#ffe0cc,stroke:#cc4f00,stroke-width:1px
    classDef metric fill:#f0f0f0,stroke:#666666,stroke-width:1px
    classDef util fill:#f0f0f0,stroke:#666666,stroke-width:1px
    classDef external fill:#e5e5e5,stroke:#888888,stroke-width:1px,stroke-dasharray: 2 2
```
