# google-deepmind/mujoco_mpc architecture

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

- Interactive diagram: https://gitdiagram.com/google-deepmind/mujoco_mpc
- Repository: https://github.com/google-deepmind/mujoco_mpc

## Overview

##### Project type and purpose
- MJPC is a research prototype for real-time predictive control with MuJoCo.
- It consists of a C++ core engine (planners, estimators, simulators, task definitions), a native GUI application, a gRPC service layer, and a Python API with demos and tests.

##### File structure
- Top-level:
– cmake/ + CMakeLists.txt → build system
– mjpc/ → C++ core source: planners/, estimators/, direct optimization, interface, tasks, main, threadpool, utilities
– docs/ → architecture, usage, GUI design
– python/ → Python package, demos, tests, setup scripts
– .github/workflows → CI build definitions
- Core modules:
– planners (gradient, iLQG, sampling, robust, cross_entropy)
– direct (multiple shooting optimizer)
– estimators (batch, Kalman, Unscented)
– interface.cc/h (bridge to MuJoCo)
– grpc/ (agent.proto, direct.proto, filter.proto + service/server implementations)
– GUI entrypoints (macos_gui.mm, app.cc/h)
– tasks/ (XML + C++ task definitions)
- Python API wraps the C++ library for scripting and demo use.

##### Extract README insights
- C++ GUI built with CMake (+ optional gRPC service).
- Python API is experimental, uses direct bindings to the core C++ library.
- Typical user flows:
– Run native GUI (`./mjpc`)
– Run gRPC server (optional)
– Run Python demos against core library or gRPC

##### Main components and interactions
a. Build System (CMake + Ninja)
- Reads CMakeLists.txt + cmake/*.cmake → configures C++ core, gRPC codegen, Python extension builds
b. C++ Core Engine
- Planners, Estimators, Direct Optimizer, Simulator Interface → depends on MuJoCo SDK
- Task Loader → reads XML definitions + assets → instantiates simulation models
- Threadpool + Utilities → concurrency support
c. gRPC Service
- agent_service, direct_service, filter_service → exposes remote-call endpoints to control engine
- Generated from .proto definitions → built into standalone server executable
d. Native GUI
- Invokes core engine APIs directly or via gRPC (if enabled)
e. Python API
- Python package `mujoco_mpc` → wraps core C++ library (via Python C-API or pybind11 if used)
- Demo scripts in python/mujoco_mpc/demos → drive engine, render via Python bindings or gRPC client
f. Tests
- C++ unit tests under mjpc/test → verify individual components
- Python tests → verify API bindings and demos

Relationships:
- Build System → compiles C++ Core + gRPC stubs + Python extension
- C++ Core ↔ MuJoCo SDK
- GUI ↔ C++ Core (direct calls)
- gRPC Service ↔ C++ Core (direct calls)
- Python API ↔ C++ Core (direct) or ↔ gRPC Service (via gRPC client stubs)
- Demos → Python API
- Tasks (XML + C++) → loaded by Core at runtime

##### Important architectural patterns
- Modular design: each planner/estimator lives in its own directory → easy to extend or swap
- Plugin-style tasks: XML descriptions + small C++ code → dynamic loading
- Layered interfaces: Core → gRPC/GUI/Python clients
- Build-time code generation: .proto → C++ stubs, CMake fetches gRPC dependency

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build System
    subgraph "Build System"
        direction TB
        BS1["CMakeLists.txt"]:::build
        BS2["cmake/CheckAvxSupport.cmake"]:::build
        BS3["cmake/FindOrFetch.cmake"]:::build
        BS4["cmake/MpcOptions.cmake"]:::build
        BS5["cmake/MujocoHarden.cmake"]:::build
        BS6["cmake/MujocoLinkOptions.cmake"]:::build
        BS7["cmake/MujocoMacOS.cmake"]:::build
    end

    %% C++ Core Engine
    subgraph "C++ Core Engine"
        direction TB
        subgraph "Interface"
            IFace["Interface & Entry"]:::core
        end
        subgraph "Threadpool & Utilities"
            TPUtil["Threadpool & Utilities"]:::core
        end
        subgraph "Planners Module"
            Planners["Planners"]:::core
        end
        subgraph "Estimators Module"
            Estimators["Estimators"]:::core
        end
        subgraph "Direct Optimizer"
            Direct["Direct Optimizer"]:::core
        end
        subgraph "Task Loader & Definitions"
            Tasks["Task Loader & Definitions"]:::core
        end
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        MuJoCo["MuJoCo SDK"]:::external
        GRPCLib["gRPC Libraries"]:::external
        PyRuntime["Python Runtime"]:::external
    end

    %% Clients
    subgraph "Clients"
        direction TB
        GUI["Native GUI"]:::client
        GRPCServer["gRPC Service"]:::client
        subgraph "Python"
            direction TB
            PyAPI["Python API"]:::client
            Demos["Python Demos"]:::client
        end
    end

    %% Tests
    subgraph "Tests"
        direction TB
        CppTests["C++ Unit Tests"]:::test
        PyTests["Python Tests"]:::test
    end

    %% Artifacts
    TaskXML["Task XML Models"]:::data

    %% Connections
    BS1 -->|configures| IFace
    BS1 -->|configures| TPUtil
    BS1 -->|configures| Planners
    BS1 -->|configures| Estimators
    BS1 -->|configures| Direct
    BS1 -->|configures| Tasks
    BS2 -->|codegen| GRPCServer
    BS3 -->|codegen| GRPCServer
    BS4 -->|codegen| PyAPI
    BS5 -->|link options| IFace
    BS6 -->|link options| IFace
    BS7 -->|macOS GUI build| GUI

    Tasks -->|XML model load| IFace
    IFace -->|function calls| MuJoCo
    TPUtil -->|concurrency support| IFace
    Planners -->|optimizers| IFace
    Estimators -->|state estimation| IFace
    Direct -->|multiple shooting| IFace

    GUI -->|direct API calls| IFace
    GRPCServer -->|direct API calls| IFace
    GRPCServer -->|uses gRPC| GRPCLib

    Demos -->|uses Python API| PyAPI
    PyAPI -->|Python C-API| IFace
    PyAPI -.->|gRPC RPC| GRPCServer
    PyAPI -->|runtime| PyRuntime

    CppTests -->|unit tests| IFace
    PyTests -->|API tests| PyAPI

    %% Click events
    click BS1 "https://github.com/google-deepmind/mujoco_mpc/blob/main/CMakeLists.txt"
    click BS2 "https://github.com/google-deepmind/mujoco_mpc/blob/main/cmake/CheckAvxSupport.cmake"
    click BS3 "https://github.com/google-deepmind/mujoco_mpc/blob/main/cmake/FindOrFetch.cmake"
    click BS4 "https://github.com/google-deepmind/mujoco_mpc/blob/main/cmake/MpcOptions.cmake"
    click BS5 "https://github.com/google-deepmind/mujoco_mpc/blob/main/cmake/MujocoHarden.cmake"
    click BS6 "https://github.com/google-deepmind/mujoco_mpc/blob/main/cmake/MujocoLinkOptions.cmake"
    click BS7 "https://github.com/google-deepmind/mujoco_mpc/blob/main/cmake/MujocoMacOS.cmake"

    click IFace "https://github.com/google-deepmind/mujoco_mpc/blob/main/mjpc/interface.cc"
    click TPUtil "https://github.com/google-deepmind/mujoco_mpc/blob/main/mjpc/threadpool.cc"
    click Planners "https://github.com/google-deepmind/mujoco_mpc/blob/main/mjpc/planners/include.cc"
    click Estimators "https://github.com/google-deepmind/mujoco_mpc/blob/main/mjpc/estimators/include.cc"
    click Direct "https://github.com/google-deepmind/mujoco_mpc/blob/main/mjpc/direct/direct.cc"
    click Tasks "https://github.com/google-deepmind/mujoco_mpc/blob/main/mjpc/task.cc"

    click GRPCServer "https://github.com/google-deepmind/mujoco_mpc/blob/main/mjpc/grpc/agent.proto"
    click GUI "https://github.com/google-deepmind/mujoco_mpc/blob/main/mjpc/app.cc"
    click PyAPI "https://github.com/google-deepmind/mujoco_mpc/blob/main/python/setup.py"
    click Demos "https://github.com/google-deepmind/mujoco_mpc/tree/main/python/mujoco_mpc/demos/agent/"

    click CppTests "https://github.com/google-deepmind/mujoco_mpc/tree/main/mjpc/test"
    click PyTests "https://github.com/google-deepmind/mujoco_mpc/blob/main/python/mujoco_mpc/agent_test.py"

    %% Styles
    classDef build fill:#FFA500,stroke:#333,stroke-width:1px
    classDef core fill:#FF6347,stroke:#333,stroke-width:1px
    classDef external fill:#87CEEB,stroke:#333,stroke-width:1px
    classDef client fill:#90EE90,stroke:#333,stroke-width:1px
    classDef test fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef data fill:#EEE8AA,stroke:#333,stroke-width:1px
```
