How deepmodeling/deepmd-kit works
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++