# deepmodeling/deepmd-kit architecture

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

- Interactive diagram: https://gitdiagram.com/deepmodeling/deepmd-kit
- Repository: https://github.com/deepmodeling/deepmd-kit

## Overview

##### Project type and purpose
- DeePMD-kit is a multi-language, multi-backend scientific software package for constructing and running deep learning–based interatomic potential models and performing molecular dynamics.
- It exposes Python CLIs and APIs, C and C++ APIs, Node.js bindings, custom operators for TensorFlow and PyTorch, and plugins for classical MD engines (LAMMPS, GROMACS, i-PI).

##### File structure
- Top-level “deepmd” directory: Python modules and entrypoints (CLI, calculator, backends for torch/tf/jax).
- “source/lib”: core C++ computational library (CPU/GPU kernels for descriptors, forces, neighbor lists).
- “source/op”: framework-specific operators (custom TF ops under source/op/tf, PT extensions under source/op/pt).
- “source/api_c” and “source/api_cc”: C and C++ language APIs (headers + implementation + tests).
- “source/nodejs”: Node.js bindings (binding.gyp, prepublish scripts).
- “source/lmp”, “source/gmx”, “source/ipi”: plugins that let LAMMPS, GROMACS, and i-PI call into DeePMD-kit.
- “examples”: usage examples demonstrating training/inference workflows.
- CI and devcontainer configs for reproducible builds and testing across languages and backends.

##### Key insights from the README
- Modular, plugin-style architecture supporting multiple ML backends (TensorFlow, PyTorch, JAX).
- Core computations are in a high-performance C++ library with CUDA/ROCm GPU support.
- Several language bindings expose the core library to Python, Node.js, C, and C++.
- External MD engines invoke DeePMD-kit via C or C++ plugin APIs.

##### Main components and their interactions
a. User Interface / Entry Points
- Python CLI and module entrypoints (“deepmd/entrypoints”, “deepmd/main.py”)
- Node.js CLI (in source/nodejs/index.js)
- Plugin entrypoints for LAMMPS, GROMACS, i-PI
b. Orchestration Layer (Python code in “deepmd/”)
- Parses JSON/YAML inputs, constructs model objects, dispatches compute
- Selects backend (TF, PT, JAX) and loads appropriate operator library
c. Backend Operators
- TensorFlow custom ops: built from source/op/tf, dynamically loaded as .so
- PyTorch C++ extensions: built from source/op/pt, loaded via torch.utils.cpp_extension
- JAX pure-Python implementations in “deepmd/jax”
d. Core Compute Library (“source/lib”)
- Descriptor computations, neighbor lists, force/virial kernels (CPU/GPU)
- Exposed via C API (source/api_c) and C++ API (source/api_cc)
e. External MD Engine Plugins
- LAMMPS plugin (source/lmp) calls into C API to compute forces during MD
- GROMACS plugin (source/gmx) built as shared library
- i-PI client (source/ipi) communicates over sockets to Python driver
f. Tests & CI
- Unit and integration tests for each language binding and backend
- GitHub Actions workflows for C++, Python, CUDA, etc.

##### Relationships and data flows
- User → Python CLI / JSON config
↳ Parser builds model graph → selects backend
↳ Loads custom op library or backend-specific Python functions
↳ Orchestration calls into core library (via C/C++ API bindings) or into pure-Python/JAX code
↳ Core library executes CPU/GPU kernels → returns potential, forces, virials
↳ Results returned to Python, printed or sent back to MD engine
- External MD Engine (LAMMPS/GROMACS/i-PI) ↔ Plugin → C/C++ API → Core library

##### Architectural patterns and design principles
- Layered architecture: UI → Python orchestration → backend operators → core compute
- Plugin pattern: each ML backend and MD engine integration is a separate plugin module
- Dependency inversion: core compute library is independent; higher layers bind to it via stable C/C++ APIs
- Separation of concerns: descriptor/fitting/inference logic lives in Python modules; heavy compute in C++

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "1. Entry Points"
        CLI_Python["Python CLI\n(deepmd/__main__.py,\ndeepmd/entrypoints/)"]:::python
        CLI_Node["Node.js CLI\n(source/nodejs/)"]:::python
        EP_LAMMPS["LAMMPS Plugin Entrypoint\n(source/lmp/)"]:::plugin
        EP_GROMACS["GROMACS Plugin Entrypoint\n(source/gmx/)"]:::plugin
        EP_IPI["i-PI Plugin Entrypoint\n(source/ipi/)"]:::plugin
        NodejsBind["Node.js Bindings\n(source/nodejs/)"]:::plugin
    end

    subgraph "2. Orchestration Layer"
        Orch["Python Orchestration\n(deepmd/)"]:::python
    end

    subgraph "3. Backend Operator Layer"
        TF_Py["TensorFlow Backend\n(deepmd/tf/)"]:::python
        TF_Ops["TensorFlow Custom Ops\n(source/op/tf/)"]:::custom
        PT_Py["PyTorch Backend\n(deepmd/pt/)"]:::python
        PT_Ops["PyTorch C++ Extensions\n(source/op/pt/)"]:::custom
        JAX["JAX Backend\n(deepmd/jax/)"]:::python
    end

    subgraph "4. Core Compute Library"
        Core["C++ Core Library\n(source/lib/)"]:::cpp
        API_C["C API Bindings\n(source/api_c/)"]:::cpp
        API_CC["C++ API Bindings\n(source/api_cc/)"]:::cpp
    end

    subgraph "5. Examples/Workflows"
        Examples["Examples\n(examples/)"]:::python
    end

    %% Data and control flows
    CLI_Python -->|"parse JSON/YAML"| Orch
    Examples -->|"demonstrates usage"| Orch
    CLI_Node -->|"invoke bindings"| NodejsBind
    NodejsBind -->|"calls"| API_C
    Orch -->|"select backend"| TF_Py
    Orch -->|"select backend"| PT_Py
    Orch -->|"select backend"| JAX
    TF_Py -->|"loads ops"| TF_Ops
    TF_Ops -->|"calls kernels"| Core
    PT_Py -->|"loads extensions"| PT_Ops
    PT_Ops -->|"calls kernels"| Core
    JAX -->|"direct compute"| Core
    Orch -->|"via C API"| API_C
    Orch -->|"via C++ API"| API_CC
    API_C -->|"executes kernels"| Core
    API_CC -->|"executes kernels"| Core
    EP_LAMMPS -->|"calls"| API_C
    EP_GROMACS -->|"calls"| API_C
    EP_IPI -->|"sockets to driver"| Orch

    %% Click Events
    click CLI_Python "https://github.com/deepmodeling/deepmd-kit/blob/r3.0/deepmd/__main__.py"
    click Orch "https://github.com/deepmodeling/deepmd-kit/tree/r3.0/deepmd/"
    click TF_Py "https://github.com/deepmodeling/deepmd-kit/tree/r3.0/deepmd/tf/"
    click TF_Ops "https://github.com/deepmodeling/deepmd-kit/tree/r3.0/source/op/tf/"
    click PT_Py "https://github.com/deepmodeling/deepmd-kit/tree/r3.0/deepmd/pt/"
    click PT_Ops "https://github.com/deepmodeling/deepmd-kit/tree/r3.0/source/op/pt/"
    click JAX "https://github.com/deepmodeling/deepmd-kit/tree/r3.0/deepmd/jax/"
    click Core "https://github.com/deepmodeling/deepmd-kit/tree/r3.0/source/lib/"
    click API_C "https://github.com/deepmodeling/deepmd-kit/tree/r3.0/source/api_c/"
    click API_CC "https://github.com/deepmodeling/deepmd-kit/tree/r3.0/source/api_cc/"
    click NodejsBind "https://github.com/deepmodeling/deepmd-kit/tree/r3.0/source/nodejs/"
    click EP_LAMMPS "https://github.com/deepmodeling/deepmd-kit/tree/r3.0/source/lmp/"
    click EP_GROMACS "https://github.com/deepmodeling/deepmd-kit/tree/r3.0/source/gmx/"
    click EP_IPI "https://github.com/deepmodeling/deepmd-kit/tree/r3.0/source/ipi/"
    click Examples "https://github.com/deepmodeling/deepmd-kit/tree/r3.0/examples/"

    %% Styles
    classDef python fill:#cce5ff,stroke:#1f78b4,stroke-width:2px
    classDef cpp fill:#ffe5b4,stroke:#ff7f0e,stroke-width:2px
    classDef custom fill:#d4edda,stroke:#28a745,stroke-width:2px
    classDef plugin fill:#e2e2e2,stroke:#6a51a3,stroke-width:2px
    classDef external fill:#f0f0f0,stroke:#6c757d,stroke-width:2px
```
