# google-deepmind/dm_control architecture

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

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

## Overview

##### Project type and purpose
- This is an open‐source Python software library (“dm_control”) for physics‐based simulation and reinforcement learning (RL) tasks, built atop the MuJoCo physics engine.
- It provides:
- Python bindings to the MuJoCo C/C++ engine (`dm_control.mujoco`)
- A suite of prebuilt RL environments (`dm_control.suite`)
- A MJCF model composer (`dm_control.mjcf`)
- A task‐composer framework (`dm_control.composer`)
- Auxiliary libraries (locomotion, manipulation, utilities)
- A viewer and rendering backends.

##### High-level components
A. User Application (your RL script or Colab tutorial)
B. dm_control Python API
- Subpackages:
– mujoco (pybind11 bindings → MuJoCo core)
– mjcf (model builder)
– composer (task/environment builder)
– suite (prepackaged envs)
– locomotion, manipulation (custom tasks)
– viewer (GUI + input handling)
– utils, autowrap, blender exporter, third_party assets
C. MuJoCo Engine (native C/C++ library)
D. Rendering backends
- GLFW (windowed hardware)
- EGL (headless hardware)
- OSMesa (software)
E. External dependencies
- OpenGL, GLEW, OS libraries
- Asset files (XML, STL/ MSH meshes)
F. Hardware / OS

##### Relationships & data flow
- Python API → calls into `dm_control.mujoco.wrapper` → binds to native MuJoCo engine
- MJCF and Composer modules → generate MJCF XML → fed into MuJoCo engine
- MuJoCo engine → computes physics → returns state / images
- Viewer → subscribes to MuJoCo state → uses chosen rendering backend → draws frames to screen
- Third‐party assets → loaded by mjcf or suite → passed to engine

##### Architectural patterns & principles
- Layered architecture:
1. Presentation (viewer GUI)
2. API layer (suite/composer/mjcf)
3. Binding layer (pybind11 wrappers)
4. Core engine (MuJoCo)
- Modular subpackages for clear separation of concern
- Extensibility via composer (plugins/hooks) and mjcf (namespacable elements)

##### Technologies, frameworks & libraries
- Python 3
- pybind11 (in mujoco.wrapper)
- GLFW / EGL / OSMesa / OpenGL / GLEW
- Protobuf & HDF5 (for mocap data)
- Blender exporter (for asset conversion)
- unittest / pytest for tests

##### Essential elements
- User → API calls
- API → Binding → Engine
- Engine → Viewer → Display
- API → Model generation → Engine
- API & Viewer → External libs (OpenGL, filesystem)
- Annotations for key modules (e.g., `dm_control.mjcf.parser`, `dm_control.viewer.gui`, `dm_control.suite.cartpole`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "User Layer"
        direction TB
        UserScript["User Script / RL Code"]:::external_gray
    end

    subgraph "dm_control Python API"
        direction TB
        subgraph "Simulation API"
            direction TB
            MujocoPkg["dm_control.mujoco"]:::sub_blue
            MJCFPkg["dm_control.mjcf"]:::sub_blue
            ComposerPkg["dm_control.composer"]:::sub_blue
            SuitePkg["dm_control.suite"]:::sub_blue
            AutowrapPkg["dm_control.autowrap"]:::sub_blue
            BlenderPkg["dm_control.blender.mujoco_exporter"]:::sub_blue
            UtilsPkg["dm_control.utils"]:::sub_blue
            RLPkg["dm_control.rl.control"]:::sub_blue
            ThirdParty["dm_control.third_party"]:::sub_blue
        end
    end

    subgraph "Binding Layer"
        direction TB
        WrapperDir["pybind11 Wrapper"]:::sub_blue
        EngineIntegration["engine.py"]:::sub_blue
        IndexModule["index.py"]:::sub_blue
        MathModule["math.py"]:::sub_blue
    end

    subgraph "Core Engine"
        direction TB
        MuJoCoCore["MuJoCo C/C++ Engine"]:::core_green
    end

    subgraph "Viewer & Rendering"
        direction TB
        ViewerPkg["dm_control.viewer"]:::sub_blue
        subgraph "Rendering Backends"
            direction TB
            GLFW["glfw_renderer.py"]:::render_orange
            EGL["egl_renderer.py"]:::render_orange
            OSMesa["osmesa_renderer.py"]:::render_orange
        end
    end

    subgraph "External Dependencies"
        direction TB
        OpenGL["OpenGL / GLEW / OS libs"]:::external_gray
        Assets["Asset Files (XML, STL, MSH)"]:::external_gray
    end

    Hardware["Hardware / OS"]:::external_gray

    %% Connections
    UserScript -->|"imports & calls"| MujocoPkg
    UserScript -->|"imports & calls"| MJCFPkg
    UserScript -->|"imports & calls"| ComposerPkg
    UserScript -->|"imports & calls"| SuitePkg
    UserScript -->|"imports & calls"| ViewerPkg

    MujocoPkg -->|"calls wrapper"| WrapperDir
    WrapperDir --> IndexModule
    WrapperDir --> MathModule
    WrapperDir --> EngineIntegration
    WrapperDir -->|"binds to"| MuJoCoCore

    MJCFPkg -->|"generates XML"| MuJoCoCore
    ComposerPkg -->|"builds tasks/envs"| MuJoCoCore
    SuitePkg -->|"loads assets & env definitions"| MuJoCoCore

    MuJoCoCore -->|"state & images"| ViewerPkg
    ViewerPkg -->|"renders via"| GLFW
    ViewerPkg -->|"renders via"| EGL
    ViewerPkg -->|"renders via"| OSMesa

    MJCFPkg -->|"loads"| Assets
    SuitePkg -->|"loads"| Assets
    ViewerPkg -->|"uses"| OpenGL
    GLFW -->|calls| OpenGL
    EGL -->|calls| OpenGL
    OSMesa -->|calls| OpenGL

    MuJoCoCore --> Hardware

    %% Click Events
    click WrapperDir "https://github.com/google-deepmind/dm_control/tree/main/dm_control/mujoco/wrapper/"
    click EngineIntegration "https://github.com/google-deepmind/dm_control/blob/main/dm_control/mujoco/engine.py"
    click IndexModule "https://github.com/google-deepmind/dm_control/blob/main/dm_control/mujoco/index.py"
    click MathModule "https://github.com/google-deepmind/dm_control/blob/main/dm_control/mujoco/math.py"
    click MJCFPkg "https://github.com/google-deepmind/dm_control/tree/main/dm_control/mjcf/"
    click MJCFPkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/mjcf/element.py"
    click MJCFPkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/mjcf/parser.py"
    click MJCFPkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/mjcf/physics.py"
    click ComposerPkg "https://github.com/google-deepmind/dm_control/tree/main/dm_control/composer/"
    click ComposerPkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/composer/environment.py"
    click ComposerPkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/composer/entity.py"
    click ComposerPkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/composer/task.py"
    click SuitePkg "https://github.com/google-deepmind/dm_control/tree/main/dm_control/suite/"
    click SuitePkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/suite/cartpole.py"
    click SuitePkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/suite/cheetah.py"
    click SuitePkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/suite/humanoid.py"
    click GLFW "https://github.com/google-deepmind/dm_control/blob/main/dm_control/_render/glfw_renderer.py"
    click EGL "https://github.com/google-deepmind/dm_control/blob/main/dm_control/_render/pyopengl/egl_renderer.py"
    click OSMesa "https://github.com/google-deepmind/dm_control/blob/main/dm_control/_render/pyopengl/osmesa_renderer.py"
    click ViewerPkg "https://github.com/google-deepmind/dm_control/tree/main/dm_control/viewer/"
    click ViewerPkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/viewer/application.py"
    click ViewerPkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/viewer/gui/glfw_gui.py"
    click ViewerPkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/viewer/renderer.py"
    click ViewerPkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/viewer/viewer.py"
    click AutowrapPkg "https://github.com/google-deepmind/dm_control/tree/main/dm_control/autowrap/"
    click AutowrapPkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/autowrap/autowrap.py"
    click AutowrapPkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/autowrap/binding_generator.py"
    click BlenderPkg "https://github.com/google-deepmind/dm_control/tree/main/dm_control/blender/mujoco_exporter/"
    click BlenderPkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/blender/mujoco_exporter/blender_scene.py"
    click BlenderPkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/blender/mujoco_exporter/mujoco_assets.py"
    click UtilsPkg "https://github.com/google-deepmind/dm_control/tree/main/dm_control/utils/"
    click UtilsPkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/utils/containers.py"
    click UtilsPkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/utils/inverse_kinematics.py"
    click UtilsPkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/utils/rewards.py"
    click RLPkg "https://github.com/google-deepmind/dm_control/blob/main/dm_control/rl/control.py"
    click ThirdParty "https://github.com/google-deepmind/dm_control/tree/main/dm_control/third_party/kinova/"
    click ThirdParty "https://github.com/google-deepmind/dm_control/tree/main/dm_control/third_party/ant/"

    %% Styles
    classDef sub_blue fill:#AED6F1,stroke:#21618C,color:#154360;
    classDef core_green fill:#ABEBC6,stroke:#196F3D,color:#145A32;
    classDef render_orange fill:#F5B041,stroke:#B9770E,color:#7E5109;
    classDef external_gray fill:#D5D8DC,stroke:#566573,color:#2E4053;
```
