docs: add docs about LAMMPS D3 dispersion (#4875)

This addresses #3099.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Added a new citation for the "DeePMD-kit v3" paper to the list of
recommended references.
* Clarified best practices for applying D3 dispersion corrections,
advising users to train models without dispersion and apply corrections
during simulation.
* Introduced a new section in the documentation explaining how to
combine DeePMD models with D3 dispersion in LAMMPS, including example
commands.
* Updated example README files with guidance on efficient model training
and use of dispersion corrections.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Jinzhe Zeng <njzjz@qq.com>
Signed-off-by: Jinzhe Zeng <jinzhe.zeng@ustc.edu.cn>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: njzjz

doc/index.rst

@@ -16,6 +16,7 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r
 
       - 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.
 
    In addition, please follow :ref:`this page <cite>` to cite the methods you used.
 

doc/model/pairtab.md

@@ -103,3 +103,10 @@ To combine with a pairwise potential, use the [linear model](./linear.md):
 ```
 
 The {ref}`rcut <model[pairtab]/rcut>` can be larger than that of the DP model.
+
+:::{note}
+The above example shows a example of combining D3 dispersion.
+However, it is more efficient to train a model using plain DFT calculations without the dispersion correction, and add the dispersion correction during the simulation via the LAMMPS [`pair_style dispersion/d3` command](https://docs.lammps.org/pair_dispersion_d3.html#pair-style-dispersion-d3-command).
+Training against data with dispersion directly is discouraged.
+See the [D3 dispersion section](../third-party/lammps-command.md#d3-dispersion) for details.
+:::

doc/third-party/lammps-command.md

@@ -229,7 +229,9 @@ dump            1 all custom 100 water.dump id type c_dipole[1] c_dipole[2] c_di
 - The `deeptensor/atom` compute is provided in the USER-DEEPMD package, which is compiled from the DeePMD-kit, visit the [DeePMD-kit website](https://github.com/deepmodeling/deepmd-kit) for more information.
 - For the issue of using a unit style for `compute deeptensor/atom`, refer to the discussions in [units](#units) of this page.
 
-## Long-range interaction
+## Combine with other commands
+
+### Long-range interaction
 
 The reciprocal space part of the long-range interaction can be calculated by LAMMPS command `kspace_style`. To use it with DeePMD-kit, one writes
 
@@ -242,7 +244,7 @@ kspace_modify	gewald 0.45
 
 Please notice that the DeePMD does nothing to the direct space part of the electrostatic interaction, because this part is assumed to be fitted in the DeePMD model (the direct space cut-off is thus the cut-off of the DeePMD model). The splitting parameter `gewald` is modified by the `kspace_modify` command.
 
-## Use of the centroid/stress/atom to get the full 3x3 "atomic-virial"
+### Use of the centroid/stress/atom to get the full 3x3 "atomic-virial"
 
 The [DeePMD-kit](https://github.com/deepmodeling/deepmd-kit) also allows the computation of per-atom stress tensor defined as:
 
@@ -262,7 +264,7 @@ see [LAMMPS doc page](https://docs.lammps.org/compute_stress_atom.html#thompson2
 v2.2.2 or previous versions passed per-atom stress (`cvatom`) with the per-atom pressure tensor, which is inconsistent with [LAMMPS's definition](https://docs.lammps.org/compute_stress_atom.html). LAMMPS defines per-atom stress as the negative of the per-atom pressure tensor. Such behavior is corrected in v2.2.3.
 :::
 
-### Examples
+#### Examples
 
 In order of computing the 9-component per-atom stress
 
@@ -274,7 +276,7 @@ Thus `c_stress` is an array with 9 components in the order `xx,yy,zz,xy,xz,yz,yx
 
 If you use this feature please cite [D. Tisi, L. Zhang, R. Bertossa, H. Wang, R. Car, S. Baroni - arXiv preprint arXiv:2108.10850, 2021](https://arxiv.org/abs/2108.10850)
 
-## Computation of heat flux
+### Computation of heat flux
 
 Using a per-atom stress tensor one can, for example, compute the heat flux defined as:
 
@@ -289,7 +291,7 @@ compute stress_ID group-ID centroid/stress/atom NULL virial
 compute flux_ID all heat/flux ke_ID pe_ID stress_ID
 ```
 
-### Examples
+#### Examples
 
 ```lammps
 compute ke all ke/atom
@@ -305,3 +307,18 @@ If you use these features please cite [D. Tisi, L. Zhang, R. Bertossa, H. Wang,
 [DP]: https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.143001
 [DP-SE]: https://dl.acm.org/doi/10.5555/3327345.3327356
 [DPSPIN]: https://doi.org/10.1103/PhysRevB.110.064427
+
+### D3 dispersion
+
+:::{note}
+Requires LAMMPS version 4Feb2025 or newer.
+:::
+
+The DP model can be trained using plain DFT calculations without the dispersion correction, and the dispersion correction can be added during the simulation via the [`pair_style dispersion/d3` command](https://docs.lammps.org/pair_dispersion_d3.html#pair-style-dispersion-d3-command).
+For example, when `water.pb` is trained against the PBE0 functional, the simulation can be performed under the PBE0-D3 level with the following commands:
+
+```lammps
+pair_style hybrid/overlay deepmd water.pb dispersion/d3 original pbe0 30.0 20.0
+pair_coeff * * O H
+pair_coeff * * O H
+```

examples/water/d3/README.md

@@ -1,5 +1,9 @@
 # DPD3
 
+> [!IMPORTANT]
+> It is more efficient to train a model using plain DFT calculations without the dispersion correction, and add the dispersion correction during the simulation via the LAMMPS [`pair_style dispersion/d3` command](https://docs.lammps.org/pair_dispersion_d3.html#pair-style-dispersion-d3-command).
+> Training against data with dispersion directly is discouraged.
+
 `dftd3.txt` tabulates D3 dispersion for each pair of types (O-O, O-H, H-H).
 It can be generated by [simple-dftd3](https://github.com/dftd3/simple-dftd3).