# xbpeng/deepmimic architecture

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

- Interactive diagram: https://gitdiagram.com/xbpeng/deepmimic
- Repository: https://github.com/xbpeng/deepmimic

## Overview

##### Main Components

A. Core Components:
- DeepMimicCore (C++ Backend)
- Animation System
- Physics Simulation
- Rendering System
- Python Training Framework
- Reinforcement Learning System
- MPI-based Distributed Training
- Data Management System

##### Detailed Component Breakdown

A. DeepMimicCore Layer:
**[Animation System]**
- Character Management
- Motion Controllers
- Kinematics System

**[Physics Simulation]**
- Bullet Physics Integration
- World Simulation
- Contact Management

**[Rendering System]**
- OpenGL Renderer
- Scene Management
- Camera System

B. Python Training Layer:
**[RL Framework]**
- Policy Networks
- Value Functions
- Experience Replay
- MPI Distribution

**[Agent Management]**
- State/Action Processing
- Reward Computation
- Policy Execution

##### Data Flow Representation

- Motion data flow from JSON files to Animation System
- State/Action flow between Physics Simulation and RL Framework
- Training data distribution across MPI workers
- Rendering output to visualization system

##### Key Interactions to Highlight

**[Motion Data] → [Animation System] → [Physics Simulation]**
- ↓
**[RL Framework] ← [State/Action Space] → [Agent]**
- ↓
**[Policy Networks] → [Character Control]**

##### Implementation Details

- SWIG interface between C++ and Python
- MPI worker distribution for parallel training
- Policy checkpoint saving/loading flow
- Visualization pipeline

##### Specific Architectural Elements

**[File System]**
- Motion Files (JSON)
- Policy Checkpoints
- Configuration Args

**[Runtime Components]**
- Scene Management
- Character Controllers
- Training Coordinators

##### External Dependencies Layer

Integration with:
- Bullet Physics
- OpenGL/GLEW
- Eigen
- TensorFlow
- MPI

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph External["External Dependencies"]
        Bullet["Bullet Physics"]:::external
        OpenGL["OpenGL/GLEW"]:::external
        Eigen["Eigen"]:::external
        TF["TensorFlow"]:::external
        MPI["MPI"]:::external
    end

    subgraph Core["DeepMimicCore (C++)"]
        subgraph AnimSystem["Animation System"]
            CharMan["Character Management"]:::core
            MotCon["Motion Controllers"]:::core
            KinSys["Kinematics System"]:::core
        end

        subgraph PhysSim["Physics Simulation"]
            WorldSim["World Simulation"]:::core
            ContMan["Contact Management"]:::core
            CharPhys["Character Physics"]:::core
        end

        subgraph RenderSys["Rendering System"]
            OGLRender["OpenGL Renderer"]:::core
            SceneMgmt["Scene Management"]:::core
            CamSys["Camera System"]:::core
        end

        SWIG["SWIG Interface"]:::interface
    end

    subgraph PyTrain["Python Training Framework"]
        subgraph RLFrame["RL Framework"]
            PolicyNet["Policy Networks"]:::python
            ValFunc["Value Functions"]:::python
            ExpReplay["Experience Replay"]:::python
            MPIDist["MPI Distribution"]:::python
        end

        subgraph AgentMgmt["Agent Management"]
            StateProc["State/Action Processing"]:::python
            RewardComp["Reward Computation"]:::python
            PolicyExec["Policy Execution"]:::python
        end
    end

    subgraph DataMgmt["Data Management"]
        MotionData["Motion Data"]:::data
        CharDef["Character Definitions"]:::data
        TrainPol["Training Policies"]:::data
        SceneConf["Scene Configurations"]:::data
    end

    %% Connections
    MotionData --> AnimSystem
    AnimSystem --> PhysSim
    PhysSim --> RLFrame
    RLFrame --> AgentMgmt
    AgentMgmt --> PhysSim
    Core --> SWIG
    SWIG --> PyTrain
    RenderSys --> OpenGL
    PhysSim --> Bullet
    MPIDist --> MPI
    PolicyNet --> TF

    %% Click Events
    click CharMan "https://github.com/xbpeng/DeepMimic/blob/master/DeepMimicCore/anim/Character.cpp"
    click MotCon "https://github.com/xbpeng/DeepMimic/blob/master/DeepMimicCore/anim/MotionController.cpp"
    click KinSys "https://github.com/xbpeng/DeepMimic/blob/master/DeepMimicCore/anim/KinTree.cpp"
    click WorldSim "https://github.com/xbpeng/DeepMimic/blob/master/DeepMimicCore/sim/World.cpp"
    click ContMan "https://github.com/xbpeng/DeepMimic/blob/master/DeepMimicCore/sim/ContactManager.cpp"
    click CharPhys "https://github.com/xbpeng/DeepMimic/blob/master/DeepMimicCore/sim/SimCharacter.cpp"
    click OGLRender "https://github.com/xbpeng/DeepMimic/blob/master/DeepMimicCore/render/DrawUtil.cpp"
    click SceneMgmt "https://github.com/xbpeng/DeepMimic/blob/master/DeepMimicCore/scenes/Scene.cpp"
    click CamSys "https://github.com/xbpeng/DeepMimic/blob/master/DeepMimicCore/render/Camera.cpp"
    click PolicyNet "https://github.com/xbpeng/DeepMimic/tree/master/learning/nets/"
    click AgentMgmt "https://github.com/xbpeng/DeepMimic/blob/master/learning/rl_agent.py"
    click MPIDist "https://github.com/xbpeng/DeepMimic/blob/master/learning/solvers/mpi_solver.py"
    click MotionData "https://github.com/xbpeng/DeepMimic/tree/master/data/motions/"
    click CharDef "https://github.com/xbpeng/DeepMimic/tree/master/data/characters/"
    click TrainPol "https://github.com/xbpeng/DeepMimic/tree/master/data/policies/"
    click SceneConf "https://github.com/xbpeng/DeepMimic/tree/master/data/controllers/"
    click SWIG "https://github.com/xbpeng/DeepMimic/blob/master/DeepMimicCore/DeepMimicCore.i"

    %% Styling
    classDef core fill:#a2d2ff
    classDef python fill:#90be6d
    classDef data fill:#f9c74f
    classDef external fill:#f94144
    classDef interface fill:#8338ec

    %% Legend
    subgraph Legend
        C++["C++ Components"]:::core
        PY["Python Components"]:::python
        DATA["Data Storage"]:::data
        EXT["External Dependencies"]:::external
        INT["Interface Layer"]:::interface
    end
```
