Skip to content
Back to search

deepmd-kit

A deep learning package for many-body potential energy representation and molecular dynamics

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/deepmodeling/deepmd-kit with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/deepmodeling/deepmd-kit'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/deepmodeling--deepmd-kit/badge.svg)](/listings/deepmodeling--deepmd-kit)

HTML

<a href="/listings/deepmodeling--deepmd-kit"><img src="/api/listings/deepmodeling--deepmd-kit/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 318 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. [<picture><source media="(prefers-color-scheme: dark)" srcset="./doc/_static/logo-dark.svg"><source media="(prefers-color-scheme: light)" srcset="./doc/_static/logo.svg"><img alt="DeePMD-kit logo" src="./doc/_static/logo.svg"></picture>][logo-guide]
  2. # DeePMD-kit
  3. **Start from a pretrained Deep Potential model, fine-tune it for your system,
  4. and deploy it at simulation scale.**
  5. [![GitHub release](https://img.shields.io/github/v/release/deepmodeling/deepmd-kit)][releases]
  6. [![offline packages](https://img.shields.io/github/downloads/deepmodeling/deepmd-kit/total?label=offline%20packages)][releases]
  7. [![conda-forge](https://img.shields.io/conda/dn/conda-forge/deepmd-kit?color=red&label=conda-forge&logo=conda-forge)](https://anaconda.org/conda-forge/deepmd-kit)
  8. [![pip install](https://img.shields.io/pypi/dm/deepmd-kit?label=pip%20install)](https://pypi.org/project/deepmd-kit/)
  9. [![docker pull](https://img.shields.io/docker/pulls/deepmodeling/deepmd-kit)](https://hub.docker.com/r/deepmodeling/deepmd-kit)
  10. [![Documentation Status](https://readthedocs.org/projects/deepmd/badge/)][documentation]
  11. [![License](https://img.shields.io/badge/license-LGPL--3.0--or--later-00a98f)](./LICENSE)
  12. [**Pretrained models**][pretrained] · [**Fine-tuning**][finetune] ·
  13. [**Documentation**][documentation] · [**Quick start**][quick-start] ·
  14. [**Model guide**][model-guide] · [**Tutorials**][tutorials] ·
  15. [**Examples**](./examples) · [**Releases**][releases]
  16. > [!IMPORTANT]
  17. > **A pretrained model can be your starting point, not just your end result.**
  18. > Download a built-in pretrained DPA4 checkpoint, fine-tune the full model for
  19. > your system, then test, export, and deploy it through the same DeePMD-kit
  20. > workflow.
  21. DeePMD-kit turns quantum-mechanical reference data into fast, scalable
  22. interatomic potentials. Use it across molecular and materials science—from
  23. finite molecules and covalent systems to periodic solids and metals—and scale
  24. from laptop fine-tuning to distributed training and MPI-parallel molecular
  25. dynamics.
  26. <p align="center">
  27. <img alt="DPA4 model family Pareto frontier for Matbench Discovery CPS and saturated inference throughput" src="./doc/_static/dpa4-cps-throughput.webp" width="1080">
  28. </p>
  29. <p align="center"><em>The DPA4 model family traces a Pareto frontier across Matbench Discovery CPS and saturated inference throughput.</em></p>
  30. ## ⚡ Why DeePMD-kit
  31. | | Advantage | What it unlocks |
  32. | --- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  33. | 🧬 | **Pretrained-first workflows** | Download [pretrained DPA4 models][dpa4-omat24], fine-tune full models, or adapt supported pretrained representations to downstream properties with [DPA-ADAPT]. |
  34. | 🏗️ | **Training from scratch** | Design a model for a new system or physical target, then train it with single-task, multi-task, and distributed workflows across supported backends. |
  35. | 🧠 | **Modern model portfolio** | For conservative energy/force interatomic potentials, start with [DPA4] for accuracy or [DPA4C] for simulation throughput and scale. |
  36. | 🧲 | **More than energy and force** | Model virials, Hessians, spin and magnetic forces, dipoles, polarizabilities, electronic density of states, atomic populations, and arbitrary intensive or extensive properties. |
  37. | 🔄 | **Backend flexibility** | Train or run supported models with [TensorFlow, PyTorch, JAX, or Paddle][backends], with backend-aware model formats and conversion paths for compatible architectures. |
  38. | 🚀 | **Performance from training to MD** | Use CPUs, CUDA GPUs, ROCm source builds, distributed training, compiled DPA4 paths, compressed DPA4C CUDA inference, AOTInductor `.pt2` export, and MPI-enabled simulation. |
  39. | 🔌 | **Deploy where science happens** | Use the CLI, Python, C, C++, or Node.js, then connect models to LAMMPS, i-PI, ASE, GROMACS, JAX MD, nvalchemi, OpenMM, Amber, CP2K, ABACUS, and more. |
  40. | 🧩 | **Open and extensible** | Compose hybrid potentials, add analytical ZBL or long-range corrections, create custom models and operators, or connect external GNNs such as MACE and NequIP through plugins. |
  41. > [!TIP]
  42. > On supported descriptors and workloads, [model compression][compression] can
  43. > deliver more than **10× inference speedup** and reduce memory usage by as much
  44. > as **20×**. Actual gains depend on the model, system, and hardware.
  45. Backend and interface support varies by model and feature. The
  46. [web documentation][documentation] marks compatibility and limitations on each
  47. feature page.
  48. ## 🧭 Two starting points, one path to dynamics
  49. ```mermaid
  50. flowchart LR
  51. A["Pretrained DPA4 model"] --> C["Fine-tune on target data"]
  52. B["Model configuration"] --> D["Train from scratch"]
  53. E["Target reference data"] --> C
  54. E --> D
  55. C --> F["Test, compress, export"]
  56. D --> F
  57. F --> G["Python and native APIs"]
  58. F --> H["Molecular dynamics"]
  59. ```
  60. 1. **Choose a starting point:** download a pretrained DPA4 checkpoint for
  61. adaptation, or configure DPA4 or DPA4C to train from scratch.
  62. 1. **Prepare target data** in DeePMD's NumPy format or convert structures and
  63. trajectories with [dpdata][data].
  64. 1. **Fine-tune or train:** adapt the full pretrained DPA4 model, or optimize a
  65. new DPA4 or DPA4C model with single-task, multi-task, and distributed
  66. training workflows.
  67. 1. **Validate and export** with [`dp test`][testing], [`dp freeze`][freeze],
  68. backend conversion, embedding extraction, and supported compression paths.
  69. 1. **Run simulation** through Python or native APIs, or load the model into a
  70. supported molecular-dynamics engine.
  71. ## 🚀 Start in minutes
  72. DeePMD-kit requires Python 3.10 or later. The fastest installation path is:
  73. ```bash
  74. curl -fsSL https://dp1s.deepmodeling.com | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 92 on GitHub
  75. dp --version
  76. dp -h
  77. ```
  78. The [installation guide][installation] covers pip, conda-forge, containers,
  79. offline packages, GPU builds, LAMMPS, i-PI, and source installation.
  80. ### Fine-tune a pretrained DPA4 model
  81. Download a built-in checkpoint, start from its matching released training
  82. configuration, and fine-tune it on your target data. This example uses DPA4-Neo,
  83. one of the recommended general-purpose sizes:
  84. ```bash
  85. dp pretrained download DPA4-Neo-OMat24-v20260805
  86. curl -fsSL \
  87. https://huggingface.co/deepmodelingcommunity/DPA4-OMat24/resolve/main/DPA4-Neo-OMat24-v20260805.json \
  88. -o input_finetune.json
  89. ```
  90. The [DPA4 OMat24 release][dpa4-omat24] provides Nano, Mini, Neo, Air, and Plus
  91. checkpoints together with their matching training configurations. The downloaded
  92. `input_finetune.json` matches the Neo checkpoint above; for another size or
  93. version, use the correspondingly named JSON file. Keep its complete `model`
  94. section unchanged, including the full-periodic-table `type_map`; replace the
  95. training and validation data, and use a smaller learning rate for fine-tuning.
  96. Then run:
  97. ```bash
  98. dp --pt train input_finetune.json \
  99. --finetune ~/.cache/deepmd/pretrained/models/DPA4-Neo-OMat24-v20260805.pt
  100. ```
  101. These are PyTorch single-task checkpoints, so no model branch selection is
  102. needed. They target inorganic materials in the OMat24 chemical space; validate
  103. accuracy before using them outside that domain.
  104. The [fine-tuning guide][finetune] covers full-model adaptation. [DPA-ADAPT]
  105. reuses supported pretrained DPA representations for downstream
  106. property-prediction tasks.
  107. Pretrained model names can also be resolved and cached automatically by
  108. Python:
  109. ```python
  110. from deepmd.infer import DeepPot
  111. potential = DeepPot("DPA4-Neo-OMat24-v20260805")
  112. ```
  113. ### Train a model from scratch
  114. Training from scratch remains a first-class workflow for new architectures,
  115. fully custom systems, and physical targets without a suitable pretrained
  116. checkpoint. Clone the examples and start with the compact water system:
  117. ```bash
  118. git clone https://github.com/deepmodeling/deepmd-kit.git
  119. cd deepmd-kit/examples/water/dpa4
  120. # Accuracy-first DPA4 model
  121. dp --pt train input.json
  122. # Or the throughput-first DPA4C model
  123. cd ../dpa4c
  124. dp --pt-expt train input.json
  125. ```
  126. Ready-to-run inputs include:
  127. - [DPA4 water training](./examples/water/dpa4/input.json)
  128. - [DPA4C high-throughput water training](./examples/water/dpa4c/input.json)
  129. - [DPA4 multi-task training](./examples/water/dpa4/input_multitask.json)
  130. - [DPA-ADAPT property prediction](./examples/dpa_adapt/README.md)
  131. For a guided end-to-end example, open the [web quick-start notebook][quick-start].
  132. ## 🧠 Choose a model family
  133. For conservative energy/force interatomic potentials, start with the DPA4
  134. family. The choice between its two primary models follows the constraint that
  135. matters most for your workload:
  136. | Priority | Start with | Why |
  137. | ---------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------- |
  138. | Highest accuracy | [DPA4] | SO(3)-equivariant message passing targets the accuracy frontier. |
  139. | Highest throughput or system scale | [DPA4C] | A compact one-hop descriptor targets the throughput frontier and supports compressed CUDA inference. |
  140. DPA4 uses the PyTorch backend (`dp --pt`). DPA4C currently uses the PyTorch
  141. Exportable backend (`dp --pt-expt`); its compressed CUDA path requires
  142. `float32`.
  143. For other physical targets, use the [model guide][model-guide] to select a
  144. compatible model and backend. The guide also compares data formats, precision,
  145. compression, and deployment constraints.
  146. <p align="center">
  147. <img alt="DPA4 and DPA4C energy and force accuracy versus saturated throughput" src="./doc/_static/dpa4-performance.webp" width="1200">
  148. </p>
  149. <p align="center"><em>For energy/force potentials, DPA4 and DPA4C span accuracy–throughput trade-offs for different deployment budgets.</em></p>
  150. ## 🔬 Go beyond conventional force fields
  151. | Goal | DeePMD-kit capabilities |
  152. | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
  153. | **Potential-energy surfaces** | Energy, atomic forces, virials, Hessians, hybrid descriptors, pair tables, and linear model combinations |
  154. | **Magnetic systems** | Spin-aware descriptors, atomic and magnetic forces, and spin-capable molecular dynamics |
  155. | **Electronic and response properties** | Dipoles, polarizabilities, density of states, atomic charge populations, and custom property heads |
  156. | **Long- and short-range physics** | DPLR electrostatics, DPRc range correction for QM/MM, and analytical ZBL bridging |
  157. | **Representation learning** | Per-atom descriptors, fitting-network features, structural embeddings, clustering, and downstream auxiliary models |
  158. Explore the complete set of [models and physical targets][model-guide] in the
  159. web documentation.
  160. ## 🔌 Deploy into the scientific ecosystem
  161. ### Inference interfaces
  162. - [Python][python-inference]
  163. - [C and C++][native-inference]
  164. - [Node.js][node-inference]
  165. - [Model embedding export][embeddings]
  166. ### Simulation and workflow integrations
  167. - [LAMMPS], [i-PI][ipi], [ASE],
  168. [JAX MD][jax-md], and [nvalchemi]
  169. - Ecosystem integrations for OpenMM, Amber, CP2K, GROMACS, ABACUS, DP-GEN, and
  170. MLatom
  171. - External MACE and NequIP models through the DeePMD-GNN plugin
  172. See the [integration hub][integrations] for maintained interfaces, third-party
  173. projects, supported scope, and installation guidance.
  174. The native C and C++ interfaces load machine-learning backends as runtime
  175. plugins. Applications can therefore open the backend required by a model
  176. without directly linking every framework.
  177. > [!NOTE]
  178. > Working with an AI coding or scientific agent? Start with
  179. > [Install with an AI agent][agent-install], or browse the
  180. > [official Agent Skills][agent-skills] for model selection, training,
  181. > fine-tuning, Python inference, and LAMMPS workflows.
  182. >
  183. > ```bash
  184. > npx -y skills add https://github.com/deepmodeling/deepmd-kit/tree/master/skills \
  185. > --skill deepmd-install -y
  186. > ```
  187. >
  188. > If direct GitHub access fails, clone the official Gitee mirror and install
  189. > from the local checkout:
  190. >
  191. > ```bash
  192. > git clone --depth 1 \
  193. > https://gitee.com/deepmodeling/deepmd-kit.git \
  194. > deepmd-kit-skill-source
  195. > npx -y skills add ./deepmd-kit-skill-source/skills \
  196. > --skill deepmd-install -y
  197. > ```
  198. ## 📚 Documentation and community
  199. - Read the [full web documentation][documentation].
  200. - Follow hands-on material in the [DeepModeling tutorials][tutorials].
  201. - Browse [examples](./examples) for training, inference, and integrations.
  202. - Ask questions or report problems in [GitHub Issues](https://github.com/deepmodeling/deepmd-kit/issues).
  203. - Join development through the [contributing guide](./CONTRIBUTING.md).
  204. ## Citation
  205. If DeePMD-kit contributes to published work, cite the general software paper
  206. that matches the version used and the method-specific papers listed in
  207. [CITATIONS.bib](./CITATIONS.bib):
  208. - Wang et al., “DeePMD-kit: A deep learning package for many-body potential
  209. energy representation and molecular dynamics,” *Computer Physics
  210. Communications* 228 (2018), 178–184 (describes the initial version).
  211. [![doi:10.1016/j.cpc.2018.03.016](https://img.shields.io/badge/DOI-10.1016%2Fj.cpc.2018.03.016-blue)](https://doi.org/10.1016/j.cpc.2018.03.016)
  212. [![Citations](https://citations.njzjz.win/10.1016/j.cpc.2018.03.016)](https://badge.dimensions.ai/details/doi/10.1016/j.cpc.2018.03.016)
  213. - Zeng et al., “DeePMD-kit v2: A software package for Deep Potential models,”
  214. *The Journal of Chemical Physics* 159 (2023), 054801 (covers features until
  215. v2.2.3).
  216. [![doi:10.1063/5.0155600](https://img.shields.io/badge/DOI-10.1063%2F5.0155600-blue)](https://doi.org/10.1063/5.0155600)
  217. [![Citations](https://citations.njzjz.win/10.1063/5.0155600)](https://badge.dimensions.ai/details/doi/10.1063/5.0155600)
  218. - Zeng et al., “DeePMD-kit v3: A Multiple-Backend Framework for Machine
  219. Learning Potentials,” *Journal of Chemical Theory and Computation* 21
  220. (2025), 4375–4385 (covers features until v3.0).
  221. [![doi:10.1021/acs.jctc.5c00340](https://img.shields.io/badge/DOI-10.1021%2Facs.jctc.5c00340-blue)](https://doi.org/10.1021/acs.jctc.5c00340)
  222. [![Citations](https://citations.njzjz.win/10.1021/acs.jctc.5c00340)](https://badge.dimensions.ai/details/doi/10.1021/acs.jctc.5c00340)
  223. ## License
  224. DeePMD-kit is licensed under the
  225. [GNU Lesser General Public License v3.0 or later](./LICENSE).
  226. [agent-install]: https://docs.deepmodeling.com/projects/deepmd/en/latest/install/install-with-agent.html
  227. [agent-skills]: https://docs.deepmodeling.com/projects/deepmd/en/latest/agent-skills.html
  228. [ase]: https://docs.deepmodeling.com/projects/deepmd/en/latest/third-party/ase.html
  229. [backends]: https://docs.deepmodeling.com/projects/deepmd/en/latest/backend.html
  230. [compression]: https://docs.deepmodeling.com/projects/deepmd/en/latest/freeze/compress.html
  231. [data]: https://docs.deepmodeling.com/projects/deepmd/en/latest/data/dpdata.html
  232. [documentation]: https://docs.deepmodeling.com/projects/deepmd/en/latest/
  233. [dpa-adapt]: https://docs.deepmodeling.com/projects/deepmd/en/latest/dpa_adapt/overview.html
  234. [dpa4]: https://docs.deepmodeling.com/projects/deepmd/en/latest/model/dpa4.html
  235. [dpa4-omat24]: https://huggingface.co/deepmodelingcommunity/DPA4-OMat24
  236. [dpa4c]: https://docs.deepmodeling.com/projects/deepmd/en/latest/model/dpa4c.html
  237. [embeddings]: https://docs.deepmodeling.com/projects/deepmd/en/latest/inference/embedding.html
  238. [finetune]: https://docs.deepmodeling.com/projects/deepmd/en/latest/train/finetuning.html
  239. [freeze]: https://docs.deepmodeling.com/projects/deepmd/en/latest/freeze/freeze.html
  240. [installation]: https://docs.deepmodeling.com/projects/deepmd/en/latest/install/easy-install.html
  241. [integrations]: https://docs.deepmodeling.com/projects/deepmd/en/latest/third-party/index.html
  242. [ipi]: https://docs.deepmodeling.com/projects/deepmd/en/latest/third-party/ipi.html
  243. [jax-md]: https://docs.deepmodeling.com/projects/deepmd/en/latest/third-party/jaxmd.html
  244. [lammps]: https://docs.deepmodeling.com/projects/deepmd/en/latest/third-party/lammps-command.html
  245. [logo-guide]: https://docs.deepmodeling.com/projects/deepmd/en/latest/logo.html
  246. [model-guide]: https://docs.deepmodeling.com/projects/deepmd/en/latest/model/index.html
  247. [native-inference]: https://docs.deepmodeling.com/projects/deepmd/en/latest/inference/cxx.html
  248. [node-inference]: https://docs.deepmodeling.com/projects/deepmd/en/latest/inference/nodejs.html
  249. [nvalchemi]: https://docs.deepmodeling.com/projects/deepmd/en/latest/third-party/nvalchemi.html
  250. [pretrained]: https://docs.deepmodeling.com/projects/deepmd/en/latest/model/pretrained.html
  251. [python-inference]: https://docs.deepmodeling.com/projects/deepmd/en/latest/inference/python.html
  252. [quick-start]: https://docs.deepmodeling.com/projects/deepmd/en/latest/getting-started/quick_start.html
  253. [releases]: https://github.com/deepmodeling/deepmd-kit/releases
  254. [testing]: https://docs.deepmodeling.com/projects/deepmd/en/latest/test/test.html
  255. [tutorials]: https://tutorials.deepmodeling.com/

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.