How google-deepmind/mujoco_mpc works
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