diff --git a/CITATIONS.bib b/CITATIONS.bib
index 0fd28323dd..97f5a10812 100644
--- a/CITATIONS.bib
+++ b/CITATIONS.bib
@@ -86,6 +86,22 @@ @article{Zeng_JChemTheoryComput_2025_v21_p4375
},
}
+@article{Han_CommunComputPhys_2018_v23_p629,
+ annote = {Deep Potential},
+ title = {
+ {Deep Potential: A General Representation of a Many-Body Potential Energy
+ Surface}
+ },
+ author = {Jiequn Han and Linfeng Zhang and Roberto Car and Weinan E},
+ journal = {Commun. Comput. Phys.},
+ year = 2018,
+ volume = 23,
+ number = 3,
+ pages = {629--639},
+ doi = {10.4208/cicp.OA-2017-0213},
+ url = {https://arxiv.org/abs/1707.01478},
+}
+
@article{Lu_CompPhysCommun_2021_v259_p107624,
annote = {GPU support},
title = {
@@ -120,6 +136,18 @@ @article{Zhang_PhysRevLett_2018_v120_p143001
doi = {10.1103/PhysRevLett.120.143001},
}
+@article{Zhang_JChemPhys_2018_v149_p34101,
+ annote = {coarse-grained model (DeePCG)},
+ title = {{DeePCG: Constructing Coarse-Grained Models via Deep Neural Networks}},
+ author = {Linfeng Zhang and Jiequn Han and Han Wang and Roberto Car and Weinan E},
+ journal = {J. Chem. Phys.},
+ year = 2018,
+ volume = 149,
+ number = 3,
+ pages = 034101,
+ doi = {10.1063/1.5027645},
+}
+
@incollection{Zhang_BookChap_NIPS_2018_v31_p4436,
annote = {DeepPot-SE (se\_e2\_a, se\_e2\_r, se\_e3, se\_atten)},
title = {
diff --git a/README.md b/README.md
index a07db0cf9c..767cafd708 100644
--- a/README.md
+++ b/README.md
@@ -1,123 +1,257 @@
-[](./doc/logo.md)
-
-______________________________________________________________________
+[][logo-guide]
# DeePMD-kit
-[](https://github.com/deepmodeling/deepmd-kit/releases)
-[](https://github.com/deepmodeling/deepmd-kit/releases)
+**From first-principles data to scalable molecular dynamics—through one open
+framework**
+
+[][releases]
+[][releases]
[](https://anaconda.org/conda-forge/deepmd-kit)
-[](https://pypi.org/project/deepmd-kit)
+[](https://pypi.org/project/deepmd-kit/)
[](https://hub.docker.com/r/deepmodeling/deepmd-kit)
-[](https://deepmd.readthedocs.io/)
+[][documentation]
+[](./LICENSE)
+
+[**Documentation**][documentation] · [**Quick start**][quick-start] ·
+[**Model guide**][model-guide] · [**Tutorials**][tutorials] ·
+[**Examples**](./examples) · [**Releases**][releases]
+
+> [!IMPORTANT]
+> DeePMD-kit turns quantum-mechanical reference data into fast, scalable
+> interatomic potentials. It combines modern Deep Potential architectures,
+> multiple machine-learning backends, adaptation workflows, and
+> simulation-ready deployment in one open-source toolkit.
+
+Use DeePMD-kit across molecular and materials science—from finite molecules and
+covalent systems to periodic solids and metals—and scale from laptop
+experiments to distributed training and MPI-parallel molecular dynamics.
+
+
+
+## ⚡ Why DeePMD-kit
+
+| | Advantage | What it unlocks |
+| --- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🧠 | **Modern model portfolio** | Start with efficient DeepPot-SE descriptors or move to [DPA][model-guide] for large atomistic models. |
+| 🧲 | **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. |
+| 🧬 | **Foundation-model workflows** | Download [pretrained DPA models][pretrained], run [multi-task learning][multi-task], fine-tune full models or LoRA adapters, extract embeddings, or adapt models to downstream properties with [DPA-ADAPT]. |
+| 🔄 | **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. |
+| 🚀 | **Performance from training to MD** | Use CPUs, CUDA GPUs, ROCm source builds, distributed training, model compression, compiled DPA-4 paths, AOTInductor `.pt2` export, and MPI-enabled simulation. |
+| 🔌 | **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. |
+| 🧩 | **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. |
+
+> [!TIP]
+> On supported descriptors and workloads, [model compression][compression] can
+> deliver more than **10× inference speedup** and reduce memory usage by as much
+> as **20×**. Actual gains depend on the model, system, and hardware.
+
+Backend and interface support varies by model and feature. The
+[web documentation][documentation] marks compatibility and limitations on each
+feature page.
+
+## 🧭 One workflow, from data to dynamics
+
+```mermaid
+flowchart LR
+ A["Reference data"] --> B["Train or adapt"]
+ B --> C["Test, compress, export"]
+ C --> D["Python and native APIs"]
+ C --> E["Molecular dynamics"]
+```
-## About DeePMD-kit
+1. **Prepare data** in DeePMD's NumPy format or convert structures and
+ trajectories with [dpdata][data].
+1. **Choose a model** from DeepPot-SE, attention-based DPA models, large atomic
+ models, or equivariant message-passing architectures.
+1. **Train and adapt** with single-task, multi-task, fine-tuning, LoRA, or
+ DPA-ADAPT workflows.
+1. **Validate and export** with [`dp test`][testing], [`dp freeze`][freeze],
+ backend conversion, embedding extraction, and supported compression paths.
+1. **Run simulation** through Python or native APIs, or load the model into a
+ supported molecular-dynamics engine.
-DeePMD-kit is a package written in Python/C++, designed to minimize the effort required to build deep learning-based model of interatomic potential energy and force field and to perform molecular dynamics (MD). This brings new hopes to addressing the accuracy-versus-efficiency dilemma in molecular simulations. Applications of DeePMD-kit span from finite molecules to extended systems and from metallic systems to chemically bonded systems.
+## 🚀 Start in minutes
-For more information, check the [documentation](https://deepmd.readthedocs.io/).
+DeePMD-kit requires Python 3.10 or later. The fastest installation path is:
-### Highlighted features
+```bash
+curl -fsSL https://dp1s.deepmodeling.com | bash
+dp --version
+dp -h
+```
-- **interfaced with multiple backends**, including TensorFlow, PyTorch, JAX, and Paddle, the most popular deep learning frameworks, making the training process highly automatic and efficient.
-- **interfaced with high-performance classical MD and quantum (path-integral) MD packages**, including LAMMPS, i-PI, AMBER, CP2K, GROMACS, OpenMM, and ABACUS.
-- **implements the Deep Potential series models**, which have been successfully applied to finite and extended systems, including organic molecules, metals, semiconductors, insulators, etc.
-- **implements MPI and GPU supports**, making it highly efficient for high-performance parallel and distributed computing.
-- **highly modularized**, easy to adapt to different descriptors for deep learning-based potential energy models.
-- **adapts pre-trained DPA models to downstream atomistic property prediction tasks with DPA-ADAPT**, a new Python API and CLI that supports frozen-descriptor scikit-learn heads, frozen property-head training, full end-to-end fine-tuning, and multi-task fine-tuning with an auxiliary force-field task. DPA-ADAPT trains on `deepmd/npy` systems and provides conversion pipelines for SMILES tables and structure or calculation files handled through dpdata. See the [DPA-ADAPT guide](doc/dpa_adapt/overview.md) and supported [input formats](doc/dpa_adapt/input_formats.md).
+The [installation guide][installation] covers pip, conda-forge, containers,
+offline packages, GPU builds, LAMMPS, i-PI, and source installation.
-### License and credits
+### Train a first model
-The project DeePMD-kit is licensed under [GNU LGPLv3.0](./LICENSE).
-If you use this code in any future publications, please cite the following publications for general purpose:
+Clone the examples and start with the compact water system:
-- Han Wang, Linfeng Zhang, Jiequn Han, and Weinan E. "DeePMD-kit: A deep learning package for many-body potential energy representation and molecular dynamics." Computer Physics Communications 228 (2018): 178-184.
- [](https://doi.org/10.1016/j.cpc.2018.03.016)
- [](https://badge.dimensions.ai/details/doi/10.1016/j.cpc.2018.03.016)
-- Jinzhe Zeng, Duo Zhang, Denghui Lu, Pinghui Mo, Zeyu Li, Yixiao Chen, Marián Rynik, Li'ang Huang, Ziyao Li, Shaochen Shi, Yingze Wang, Haotian Ye, Ping Tuo, Jiabin Yang, Ye Ding, Yifan Li, Davide Tisi, Qiyu Zeng, Han Bao, Yu Xia, Jiameng Huang, Koki Muraoka, Yibo Wang, Junhan Chang, Fengbo Yuan, Sigbjørn Løland Bore, Chun Cai, Yinnian Lin, Bo Wang, Jiayan Xu, Jia-Xin Zhu, Chenxing Luo, Yuzhi Zhang, Rhys E. A. Goodall, Wenshuo Liang, Anurag Kumar Singh, Sikai Yao, Jingchao Zhang, Renata Wentzcovitch, Jiequn Han, Jie Liu, Weile Jia, Darrin M. York, Weinan E, Roberto Car, Linfeng Zhang, Han Wang. "DeePMD-kit v2: A software package for deep potential models." J. Chem. Phys. 159 (2023): 054801.
- [](https://doi.org/10.1063/5.0155600)
- [](https://badge.dimensions.ai/details/doi/10.1063/5.0155600)
-- Jinzhe Zeng, Duo Zhang, Anyang Peng, Xiangyu Zhang, Sensen He, Yan Wang, Xinzijian Liu, Hangrui Bi, Yifan Li, Chun Cai, Chengqian Zhang, Yiming Du, Jia-Xin Zhu, Pinghui Mo, Zhengtao Huang, Qiyu Zeng, Shaochen Shi, Xuejian Qin, Zhaoxi Yu, Chenxing Luo, Ye Ding, Yun-Pei Liu, Ruosong Shi, Zhenyu Wang, Sigbjørn Løland Bore, Junhan Chang, Zhe Deng, Zhaohan Ding, Siyuan Han, Wanrun Jiang, Guolin Ke, Zhaoqing Liu, Denghui Lu, Koki Muraoka, Hananeh Oliaei, Anurag Kumar Singh, Haohui Que, Weihong Xu, Zhangmancang Xu, Yong-Bin Zhuang, Jiayu Dai, Timothy J. Giese, Weile Jia, Ben Xu, Darrin M. York, Linfeng Zhang, Han Wang. "DeePMD-kit v3: A Multiple-Backend Framework for Machine Learning Potentials." J. Chem. Theory Comput. 21 (2025): 4375-4385.
- [](https://doi.org/10.1021/acs.jctc.5c00340)
- [](https://badge.dimensions.ai/details/doi/10.1021/acs.jctc.5c00340)
+```bash
+git clone https://github.com/deepmodeling/deepmd-kit.git
+cd deepmd-kit/examples/water/se_e2_a
-In addition, please follow [the bib file](CITATIONS.bib) to cite the methods you used.
+# TensorFlow backend
+dp train input.json
-### Highlights in major versions
+# Or PyTorch
+dp --pt train input_torch.json
+```
-#### Initial version
+Ready-to-run inputs include:
-The goal of Deep Potential is to employ deep learning techniques and realize an inter-atomic potential energy model that is general, accurate, computationally efficient and scalable. The key component is to respect the extensive and symmetry-invariant properties of a potential energy model by assigning a local reference frame and a local environment to each atom. Each environment contains a finite number of atoms, whose local coordinates are arranged in a symmetry-preserving way. These local coordinates are then transformed, through a sub-network, to so-called _atomic energy_. Summing up all the atomic energies gives the potential energy of the system.
+- [DPA-3 water training](./examples/water/dpa3/input_torch.json)
+- [DPA-4 water training](./examples/water/dpa4/input.json)
+- [Multi-task training](./examples/water_multi_task/pytorch_example/input_torch.json)
+- [DPA-ADAPT property prediction](./examples/dpa_adapt/README.md)
-The initial proof of concept is in the [Deep Potential][1] paper, which employed an approach that was devised to train the neural network model with the potential energy only. With typical _ab initio_ molecular dynamics (AIMD) datasets this is insufficient to reproduce the trajectories. The Deep Potential Molecular Dynamics ([DeePMD][2]) model overcomes this limitation. In addition, the learning process in DeePMD improves significantly over the Deep Potential method thanks to the introduction of a flexible family of loss functions. The NN potential constructed in this way reproduces accurately the AIMD trajectories, both classical and quantum (path integral), in extended and finite systems, at a cost that scales linearly with system size and is always several orders of magnitude lower than that of equivalent AIMD simulations.
+For a guided end-to-end example, open the [web quick-start notebook][quick-start].
-Although highly efficient, the original Deep Potential model satisfies the extensive and symmetry-invariant properties of a potential energy model at the price of introducing discontinuities in the model. This has negligible influence on a trajectory from canonical sampling but might not be sufficient for calculations of dynamical and mechanical properties. These points motivated us to develop the Deep Potential-Smooth Edition ([DeepPot-SE][3]) model, which replaces the non-smooth local frame with a smooth and adaptive embedding network. DeepPot-SE shows great ability in modeling many kinds of systems that are of interest in the fields of physics, chemistry, biology, and materials science.
+### Start from a pretrained DPA model
-In addition to building up potential energy models, DeePMD-kit can also be used to build up coarse-grained models. In these models, the quantity that we want to parameterize is the free energy, or the coarse-grained potential, of the coarse-grained particles. See the [DeePCG paper][4] for more details.
+Built-in models can be downloaded explicitly:
-#### v1
+```bash
+dp pretrained download DPA-3.2-5M
+```
-- Code refactor to make it highly modularized.
-- GPU support for descriptors.
+They can also be resolved and cached automatically by Python:
-#### v2
+```python
+from deepmd.infer import DeepPot
-- Model compression. Accelerate the efficiency of model inference 4-15 times.
-- New descriptors. Including `se_e2_r`, `se_e3`, and `se_atten` (DPA-1).
-- Hybridization of descriptors. Hybrid descriptor constructed from the concatenation of several descriptors.
-- Atom type embedding. Enable atom-type embedding to decline training complexity and refine performance.
-- Training and inference of the dipole (vector) and polarizability (matrix).
-- Split of training and validation dataset.
-- Optimized training on GPUs, including CUDA and ROCm.
-- Non-von-Neumann.
-- C API to interface with the third-party packages.
+potential = DeepPot("DPA-3.2-5M")
+```
-See [our v2 paper](https://doi.org/10.1063/5.0155600) for details of all features until v2.2.3.
+### Fine-tune a pretrained model
-#### v3
+Fine-tuning adapts a pretrained checkpoint to your dataset without training
+from scratch:
-- Multiple backends supported. Add PyTorch and JAX backends.
-- The DPA2 and DPA3 models.
-- Plugin mechanisms for external models.
+```bash
+dp pretrained download DPA-3.2-5M
+dp --pt train input.json --finetune ~/.cache/deepmd/pretrained/models/DPA-3.2-5M.pt --model-branch
+```
-See [our v3 paper](https://doi.org/10.1021/acs.jctc.5c00340) for details of all features until v3.0.
+`DPA-3.2-5M` is a PyTorch multi-task checkpoint: run the trainer in PyTorch
+mode with `dp --pt` and select the branch that matches your system with
+`--model-branch` (list them with
+`dp --pt show ~/.cache/deepmd/pretrained/models/DPA-3.2-5M.pt model-branch`).
-## Install and use DeePMD-kit
+The [fine-tuning guide][finetune] covers full-model and LoRA adaptation, and
+[DPA-ADAPT] adapts pretrained DPA representations to downstream
+property-prediction tasks.
-Just copy and paste in 1s, and let it run.
+## 🧠 Choose a model family
-```sh
-curl -fsSL https://dp1s.deepmodeling.com | bash
-```
+DeepPot-SE is a strong default: efficient, established, and broadly supported.
+For large atomistic models, start with [DPA-4](https://docs.deepmodeling.com/projects/deepmd/en/latest/model/dpa4.html).
-Please read the [online documentation](https://deepmd.readthedocs.io/) for details and alternative installation methods.
+Use the [model guide][model-guide] to compare model families, supported backends,
+targets, data formats, precision, compression, and deployment constraints.
-Then, read on for a brief overview of the usage of DeePMD-kit. You may start with the first step:
+## 🔬 Go beyond conventional force fields
-```sh
-dp
-```
+| Goal | DeePMD-kit capabilities |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| **Potential-energy surfaces** | Energy, atomic forces, virials, Hessians, hybrid descriptors, pair tables, and linear model combinations |
+| **Magnetic systems** | Spin-aware descriptors, atomic and magnetic forces, and spin-capable molecular dynamics |
+| **Electronic and response properties** | Dipoles, polarizabilities, density of states, atomic charge populations, and custom property heads |
+| **Long- and short-range physics** | DPLR electrostatics, DPRc range correction for QM/MM, and analytical ZBL bridging |
+| **Representation learning** | Per-atom descriptors, fitting-network features, structural embeddings, clustering, and downstream auxiliary models |
+
+Explore the complete set of [models and physical targets][model-guide] in the
+web documentation.
+
+## 🔌 Deploy into the scientific ecosystem
+
+### Inference interfaces
+
+- [Python][python-inference]
+- [C and C++][native-inference]
+- [Node.js][node-inference]
+- [Model embedding export][embeddings]
+
+### Simulation and workflow integrations
+
+- [LAMMPS], [i-PI][ipi], [ASE],
+ [JAX MD][jax-md], and [nvalchemi]
+- Ecosystem integrations for OpenMM, Amber, CP2K, GROMACS, ABACUS, DP-GEN, and
+ MLatom
+- External MACE and NequIP models through the DeePMD-GNN plugin
+
+See the [integration hub][integrations] for maintained interfaces, third-party
+projects, supported scope, and installation guidance.
-## Code structure
+The native C and C++ interfaces load machine-learning backends as runtime
+plugins. Applications can therefore open the backend required by a model
+without directly linking every framework.
-The code is organized as follows:
+> [!NOTE]
+> Working with an AI coding or scientific agent? DeePMD-kit ships
+> [official Agent Skills][agent-skills] for model selection, training,
+> fine-tuning, Python inference, and LAMMPS workflows.
-- `examples`: examples.
-- `deepmd`: DeePMD-kit python modules.
-- `dpa_adapt`: DPA-ADAPT package for adapting pre-trained DPA models; see the [guide](doc/dpa_adapt/overview.md) and [input formats](doc/dpa_adapt/input_formats.md).
-- `source/lib`: source code of the core library.
-- `source/op`: Operator (OP) implementation.
-- `source/api_cc`: source code of DeePMD-kit C++ API.
-- `source/api_c`: source code of the C API.
-- `source/nodejs`: source code of the Node.js API.
-- `source/ipi`: source code of i-PI client.
-- `source/lmp`: source code of LAMMPS module.
+## 📚 Documentation and community
-# Contributing
+- Read the [full web documentation][documentation].
+- Follow hands-on material in the [DeepModeling tutorials][tutorials].
+- Browse [examples](./examples) for training, inference, and integrations.
+- Ask questions or report problems in [GitHub Issues](https://github.com/deepmodeling/deepmd-kit/issues).
+- Join development through the [contributing guide](./CONTRIBUTING.md).
-See [DeePMD-kit Contributing Guide](CONTRIBUTING.md) to become a contributor! 🤓
+## Citation
+
+If DeePMD-kit contributes to published work, cite the general software paper
+that matches the version used and the method-specific papers listed in
+[CITATIONS.bib](./CITATIONS.bib):
+
+- Wang et al., “DeePMD-kit: A deep learning package for many-body potential
+ energy representation and molecular dynamics,” *Computer Physics
+ Communications* 228 (2018), 178–184 (describes the initial version).
+ [](https://doi.org/10.1016/j.cpc.2018.03.016)
+ [](https://badge.dimensions.ai/details/doi/10.1016/j.cpc.2018.03.016)
+- Zeng et al., “DeePMD-kit v2: A software package for Deep Potential models,”
+ *The Journal of Chemical Physics* 159 (2023), 054801 (covers features until
+ v2.2.3).
+ [](https://doi.org/10.1063/5.0155600)
+ [](https://badge.dimensions.ai/details/doi/10.1063/5.0155600)
+- Zeng et al., “DeePMD-kit v3: A Multiple-Backend Framework for Machine
+ Learning Potentials,” *Journal of Chemical Theory and Computation* 21
+ (2025), 4375–4385 (covers features until v3.0).
+ [](https://doi.org/10.1021/acs.jctc.5c00340)
+ [](https://badge.dimensions.ai/details/doi/10.1021/acs.jctc.5c00340)
-[1]: https://arxiv.org/abs/1707.01478
-[2]: https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.143001
-[3]: https://arxiv.org/abs/1805.09003
-[4]: https://aip.scitation.org/doi/full/10.1063/1.5027645
+## License
+
+DeePMD-kit is licensed under the
+[GNU Lesser General Public License v3.0 or later](./LICENSE).
+
+[agent-skills]: https://docs.deepmodeling.com/projects/deepmd/en/latest/agent-skills.html
+[ase]: https://docs.deepmodeling.com/projects/deepmd/en/latest/third-party/ase.html
+[backends]: https://docs.deepmodeling.com/projects/deepmd/en/latest/backend.html
+[compression]: https://docs.deepmodeling.com/projects/deepmd/en/latest/freeze/compress.html
+[data]: https://docs.deepmodeling.com/projects/deepmd/en/latest/data/dpdata.html
+[documentation]: https://docs.deepmodeling.com/projects/deepmd/en/latest/
+[dpa-adapt]: https://docs.deepmodeling.com/projects/deepmd/en/latest/dpa_adapt/overview.html
+[embeddings]: https://docs.deepmodeling.com/projects/deepmd/en/latest/inference/embedding.html
+[finetune]: https://docs.deepmodeling.com/projects/deepmd/en/latest/train/finetuning.html
+[freeze]: https://docs.deepmodeling.com/projects/deepmd/en/latest/freeze/freeze.html
+[installation]: https://docs.deepmodeling.com/projects/deepmd/en/latest/install/easy-install.html
+[integrations]: https://docs.deepmodeling.com/projects/deepmd/en/latest/third-party/index.html
+[ipi]: https://docs.deepmodeling.com/projects/deepmd/en/latest/third-party/ipi.html
+[jax-md]: https://docs.deepmodeling.com/projects/deepmd/en/latest/third-party/jaxmd.html
+[lammps]: https://docs.deepmodeling.com/projects/deepmd/en/latest/third-party/lammps-command.html
+[logo-guide]: https://docs.deepmodeling.com/projects/deepmd/en/latest/logo.html
+[model-guide]: https://docs.deepmodeling.com/projects/deepmd/en/latest/model/index.html
+[multi-task]: https://docs.deepmodeling.com/projects/deepmd/en/latest/train/multi-task-training.html
+[native-inference]: https://docs.deepmodeling.com/projects/deepmd/en/latest/inference/cxx.html
+[node-inference]: https://docs.deepmodeling.com/projects/deepmd/en/latest/inference/nodejs.html
+[nvalchemi]: https://docs.deepmodeling.com/projects/deepmd/en/latest/third-party/nvalchemi.html
+[pretrained]: https://docs.deepmodeling.com/projects/deepmd/en/latest/model/pretrained.html
+[python-inference]: https://docs.deepmodeling.com/projects/deepmd/en/latest/inference/python.html
+[quick-start]: https://docs.deepmodeling.com/projects/deepmd/en/latest/getting-started/quick_start.html
+[releases]: https://github.com/deepmodeling/deepmd-kit/releases
+[testing]: https://docs.deepmodeling.com/projects/deepmd/en/latest/test/test.html
+[tutorials]: https://tutorials.deepmodeling.com/
diff --git a/doc/_static/dpa4-performance.webp b/doc/_static/dpa4-performance.webp
new file mode 100644
index 0000000000..6ef18f1a47
Binary files /dev/null and b/doc/_static/dpa4-performance.webp differ
diff --git a/doc/index.rst b/doc/index.rst
index 6e698be273..481782ae9e 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -1,24 +1,286 @@
-.. deepmd-kit documentation master file, created by
- sphinx-quickstart on Sat Nov 21 18:36:24 2020.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
+===========
+DeePMD-kit
+===========
-==========================
-DeePMD-kit's documentation
-==========================
+.. rst-class:: lead
-DeePMD-kit is a package written in Python/C++, designed to minimize the effort required to build deep learning-based models of interatomic potential energy and force field and to perform molecular dynamics (MD). This brings new hopes to addressing the accuracy-versus-efficiency dilemma in molecular simulations. Applications of DeePMD-kit span from finite molecules to extended systems and from metallic systems to chemically bonded systems.
+ From first-principles data to scalable molecular dynamics—through one open
+ framework.
-.. Important::
+DeePMD-kit turns quantum-mechanical reference data into fast, scalable
+interatomic potentials. It combines modern Deep Potential architectures,
+multiple machine-learning backends, adaptation workflows, and
+simulation-ready deployment in one open-source toolkit.
- The project DeePMD-kit is licensed under `GNU LGPLv3.0 `_.
- If you use this code in any future publications, please cite the following publications for general purpose:
+Use it across molecular and materials science—from finite molecules and
+covalent systems to periodic solids and metals—and scale from laptop
+experiments to distributed training and MPI-parallel molecular dynamics.
- - Han Wang, Linfeng Zhang, Jiequn Han, and Weinan E. "DeePMD-kit: A deep learning package for many-body potential energy representation and molecular dynamics." Computer Physics Communications 228 (2018): 178-184.
- - Jinzhe Zeng, Duo Zhang, Denghui Lu, Pinghui Mo, Zeyu Li, Yixiao Chen, Marián Rynik, Li'ang Huang, Ziyao Li, Shaochen Shi, Yingze Wang, Haotian Ye, Ping Tuo, Jiabin Yang, Ye Ding, Yifan Li, Davide Tisi, Qiyu Zeng, Han Bao, Yu Xia, Jiameng Huang, Koki Muraoka, Yibo Wang, Junhan Chang, Fengbo Yuan, Sigbjørn Løland Bore, Chun Cai, Yinnian Lin, Bo Wang, Jiayan Xu, Jia-Xin Zhu, Chenxing Luo, Yuzhi Zhang, Rhys E. A. Goodall, Wenshuo Liang, Anurag Kumar Singh, Sikai Yao, Jingchao Zhang, Renata Wentzcovitch, Jiequn Han, Jie Liu, Weile Jia, Darrin M. York, Weinan E, Roberto Car, Linfeng Zhang, Han Wang. "DeePMD-kit v2: A software package for Deep Potential models." J. Chem. Phys., 159, 054801 (2023).
- - Jinzhe Zeng, Duo Zhang, Anyang Peng, Xiangyu Zhang, Sensen He, Yan Wang, Xinzijian Liu, Hangrui Bi, Yifan Li, Chun Cai, Chengqian Zhang, Yiming Du, Jia-Xin Zhu, Pinghui Mo, Zhengtao Huang, Qiyu Zeng, Shaochen Shi, Xuejian Qin, Zhaoxi Yu, Chenxing Luo, Ye Ding, Yun-Pei Liu, Ruosong Shi, Zhenyu Wang, Sigbjørn Løland Bore, Junhan Chang, Zhe Deng, Zhaohan Ding, Siyuan Han, Wanrun Jiang, Guolin Ke, Zhaoqing Liu, Denghui Lu, Koki Muraoka, Hananeh Oliaei, Anurag Kumar Singh, Haohui Que, Weihong Xu, Zhangmancang Xu, Yong-Bin Zhuang, Jiayu Dai, Timothy J. Giese, Weile Jia, Ben Xu, Darrin M. York, Linfeng Zhang, Han Wang. "DeePMD-kit v3: A Multiple-Backend Framework for Machine Learning Potentials." J. Chem. Theory Comput. 21 (2025): 4375-4385.
+.. figure:: _static/dpa4-performance.webp
+ :alt: DPA4 delivers competitive energy and force accuracy at high throughput
+ :width: 100%
+ :align: center
- In addition, please follow :ref:`this page ` to cite the methods you used.
+ DPA4 delivers competitive energy and force accuracy at high throughput.
+
+Choose your path
+================
+
+.. grid:: 1 2 2 4
+ :gutter: 3
+
+ .. grid-item-card:: 🚀 Install and start
+ :link: getting-started/index
+ :link-type: doc
+ :shadow: md
+
+ Install DeePMD-kit, prepare a small dataset, and train your first model.
+
+ .. grid-item-card:: 🧠 Choose a model
+ :link: model/index
+ :link-type: doc
+ :shadow: md
+
+ Compare DeepPot-SE, DPA-1, DPA-2, DPA-3, DPA-4, and specialized
+ physics models.
+
+ .. grid-item-card:: 🧬 Train and adapt
+ :link: train/index
+ :link-type: doc
+ :shadow: md
+
+ Run single-task or multi-task training, fine-tuning, LoRA, and
+ pretrained-model workflows.
+
+ .. grid-item-card:: 🔌 Deploy and integrate
+ :link: third-party/index
+ :link-type: doc
+ :shadow: md
+
+ Move models into Python, native APIs, LAMMPS, i-PI, ASE, GROMACS, and
+ the wider simulation ecosystem.
+
+Why DeePMD-kit
+==============
+
+.. grid:: 1 2 2 3
+ :gutter: 3
+
+ .. grid-item-card:: Modern potential architectures
+ :shadow: sm
+
+ Use efficient DeepPot-SE descriptors, attention-based DPA models, large
+ atomic models, and SO(3)-equivariant DPA-4.
+
+ .. grid-item-card:: Broad physical targets
+ :shadow: sm
+
+ Learn energies, forces, virials, Hessians, spin, dipoles,
+ polarizabilities, density of states, atomic populations, and custom
+ properties.
+
+ .. grid-item-card:: Foundation-model workflows
+ :shadow: sm
+
+ Download built-in DPA models, share representations across tasks,
+ fine-tune full models or LoRA adapters, and use DPA-ADAPT for downstream
+ prediction.
+
+ .. grid-item-card:: Multi-backend framework
+ :link: backend
+ :link-type: doc
+ :shadow: sm
+
+ Work with TensorFlow, PyTorch, JAX, or Paddle and use backend-aware model
+ formats, conversion, and runtime plugins.
+
+ .. grid-item-card:: Performance at scale
+ :shadow: sm
+
+ Run on CPUs and GPUs, distribute training, compress supported models,
+ export compiled ``.pt2`` artifacts, and drive MPI-parallel simulations.
+
+ .. grid-item-card:: Open scientific ecosystem
+ :link: third-party/index
+ :link-type: doc
+ :shadow: sm
+
+ Connect to simulation engines, workflow tools, native applications, and
+ external GNN models through documented interfaces and plugins.
+
+.. tip::
+
+ On supported descriptors and workloads,
+ :doc:`model compression ` can deliver more than
+ **10× inference speedup** and reduce memory usage by as much as **20×**.
+ Actual gains depend on the model, system, and hardware.
+
+From data to dynamics
+=====================
+
+.. grid:: 1 2 3 5
+ :gutter: 2
+
+ .. grid-item-card:: 1 · Prepare
+ :link: data/index
+ :link-type: doc
+
+ Convert reference structures and labels into DeePMD data.
+
+ .. grid-item-card:: 2 · Model
+ :link: model/index
+ :link-type: doc
+
+ Select a descriptor, physical target, and backend.
+
+ .. grid-item-card:: 3 · Train
+ :link: train/index
+ :link-type: doc
+
+ Train from scratch or adapt a pretrained model.
+
+ .. grid-item-card:: 4 · Validate
+ :link: test/index
+ :link-type: doc
+
+ Test accuracy, inspect deviation, freeze, and compress.
+
+ .. grid-item-card:: 5 · Simulate
+ :link: inference/index
+ :link-type: doc
+
+ Run inference directly or deploy into molecular dynamics.
+
+Choose a model family
+=====================
+
+.. list-table::
+ :header-rows: 1
+ :widths: 24 76
+
+ * - Family
+ - A strong starting point when you need
+ * - :doc:`DeepPot-SE `
+ - An efficient, established baseline with broad backend and deployment
+ support.
+ * - :doc:`DPA-1 `
+ - Attention-based local representations and type embedding.
+ * - :doc:`DPA-2 `
+ - Multi-task pretraining, shared representations, and smooth conservative
+ potentials.
+ * - :doc:`DPA-3 `
+ - Message passing over line-graph representations and broad chemical
+ coverage.
+ * - :doc:`DPA-4 `
+ - SO(3)-equivariant learning, LoRA fine-tuning, optional ZBL bridging,
+ spin support, and compiled ``.pt2`` deployment.
+
+More than conventional force fields
+===================================
+
+.. grid:: 1 2 2 3
+ :gutter: 3
+
+ .. grid-item-card:: 🧲 Spin and magnetism
+ :link: model/train-energy-spin
+ :link-type: doc
+
+ Train spin-aware potentials with atomic and magnetic force targets.
+
+ .. grid-item-card:: ⚛️ Long- and short-range physics
+ :link: model/dplr
+ :link-type: doc
+
+ Combine learned local interactions with DPLR electrostatics, DPRc range
+ correction, pair tables, or analytical ZBL bridging.
+
+ .. grid-item-card:: 📊 Properties and embeddings
+ :link: inference/embedding
+ :link-type: doc
+
+ Predict electronic or structural properties and export learned
+ representations for analysis or downstream models.
+
+New and noteworthy
+==================
+
+.. grid:: 1 2 2 4
+ :gutter: 3
+
+ .. grid-item-card:: DPA-4
+ :link: model/dpa4
+ :link-type: doc
+ :shadow: sm
+
+ Equivariant message passing, LoRA, ZBL, spin, compiled inference, and
+ LAMMPS deployment.
+
+ .. grid-item-card:: Pretrained DPA models
+ :link: model/pretrained
+ :link-type: doc
+ :shadow: sm
+
+ Resolve built-in model names directly or download checkpoints to a local
+ cache.
+
+ .. grid-item-card:: DPA-ADAPT
+ :link: dpa_adapt/index
+ :link-type: doc
+ :shadow: sm
+
+ Adapt pretrained DPA representations to downstream atomistic property
+ tasks.
+
+ .. grid-item-card:: Official Agent Skills
+ :link: agent-skills
+ :link-type: doc
+ :shadow: sm
+
+ Give AI agents reproducible guidance for training, fine-tuning,
+ inference, and LAMMPS workflows.
+
+Citation
+========
+
+If you use DeePMD-kit in published work, cite the general software publication
+that matches the version used:
+
+* Han Wang, Linfeng Zhang, Jiequn Han, and Weinan E. "DeePMD-kit: A deep
+ learning package for many-body potential energy representation and molecular
+ dynamics." *Computer Physics Communications* 228 (2018): 178–184.
+ `DOI: 10.1016/j.cpc.2018.03.016
+ `_.
+* Jinzhe Zeng, Duo Zhang, Denghui Lu, Pinghui Mo, Zeyu Li, Yixiao Chen,
+ Marián Rynik, Li'ang Huang, Ziyao Li, Shaochen Shi, Yingze Wang, Haotian Ye,
+ Ping Tuo, Jiabin Yang, Ye Ding, Yifan Li, Davide Tisi, Qiyu Zeng, Han Bao,
+ Yu Xia, Jiameng Huang, Koki Muraoka, Yibo Wang, Junhan Chang, Fengbo Yuan,
+ Sigbjørn Løland Bore, Chun Cai, Yinnian Lin, Bo Wang, Jiayan Xu, Jia-Xin Zhu,
+ Chenxing Luo, Yuzhi Zhang, Rhys E. A. Goodall, Wenshuo Liang, Anurag Kumar
+ Singh, Sikai Yao, Jingchao Zhang, Renata Wentzcovitch, Jiequn Han, Jie Liu,
+ Weile Jia, Darrin M. York, Weinan E, Roberto Car, Linfeng Zhang, and Han
+ Wang. "DeePMD-kit v2: A software package for Deep Potential models."
+ *The Journal of Chemical Physics* 159 (2023): 054801.
+ `DOI: 10.1063/5.0155600 `_.
+* Jinzhe Zeng, Duo Zhang, Anyang Peng, Xiangyu Zhang, Sensen He, Yan Wang,
+ Xinzijian Liu, Hangrui Bi, Yifan Li, Chun Cai, Chengqian Zhang, Yiming Du,
+ Jia-Xin Zhu, Pinghui Mo, Zhengtao Huang, Qiyu Zeng, Shaochen Shi, Xuejian
+ Qin, Zhaoxi Yu, Chenxing Luo, Ye Ding, Yun-Pei Liu, Ruosong Shi, Zhenyu Wang,
+ Sigbjørn Løland Bore, Junhan Chang, Zhe Deng, Zhaohan Ding, Siyuan Han,
+ Wanrun Jiang, Guolin Ke, Zhaoqing Liu, Denghui Lu, Koki Muraoka, Hananeh
+ Oliaei, Anurag Kumar Singh, Haohui Que, Weihong Xu, Zhangmancang Xu,
+ Yong-Bin Zhuang, Jiayu Dai, Timothy J. Giese, Weile Jia, Ben Xu, Darrin M.
+ York, Linfeng Zhang, and Han Wang. "DeePMD-kit v3: A Multiple-Backend
+ Framework for Machine Learning Potentials." *Journal of Chemical Theory and
+ Computation* 21 (2025): 4375–4385.
+ `DOI: 10.1021/acs.jctc.5c00340
+ `_.
+
+Follow the :doc:`citation guide ` for the method-specific publications
+required by the models and features used in your work.
+
+.. note::
+
+ DeePMD-kit is licensed under the :doc:`GNU LGPL-3.0-or-later `.
.. _getting-started:
@@ -33,7 +295,7 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r
.. toctree::
:maxdepth: 3
:numbered:
- :caption: Advanced
+ :caption: User Guide
backend
install/index
@@ -51,12 +313,11 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r
env
troubleshooting/index
-
.. _tutorial:
.. toctree::
:maxdepth: 2
- :caption: Tutorial
+ :caption: Tutorials and Publications
Tutorials
Publications
@@ -79,7 +340,6 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r
api_c/api_c
api_core/api_core
-
.. _project-details:
.. toctree::
@@ -90,6 +350,8 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r
credits
logo
+Indices
+-------
* :ref:`genindex`
* :ref:`modindex`
