Merge branch 'deepmodeling:devel' into devel

deepmodeling · Feb 3, 2024 · 46f17ef · 46f17ef
2 parents f75dab6 + 677d936
commit 46f17ef
Show file tree

Hide file tree

Showing 426 changed files with 25,937 additions and 3,210 deletions.
diff --git a/.github/workflows/build_wheel.yml b/.github/workflows/build_wheel.yml
@@ -41,12 +41,12 @@ jobs:
             cuda_version: 11.8
             dp_pkg_name: deepmd-kit-cu11
           # macos-x86-64
-          - os: macos-latest
+          - os: macos-13
             python: 311
             platform_id: macosx_x86_64
             dp_variant: cpu
           # macos-arm64
-          - os: macos-latest
+          - os: macos-14
             python: 311
             platform_id: macosx_arm64
             dp_variant: cpu

diff --git a/.github/workflows/test_cuda.yml b/.github/workflows/test_cuda.yml
@@ -34,16 +34,17 @@ jobs:
          && sudo apt-get -y install cuda-12-2 libcudnn8=8.9.5.*-1+cuda12.2
       if: false  # skip as we use nvidia image
     - name: Set PyPI mirror for Aliyun cloud machine
-      run: python -m pip config --user set global.index-url https://mirrors.aliyun.com/pypi/simple/
+      run: python -m pip config --user set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/
     - run: python -m pip install -U "pip>=21.3.1,!=23.0.0"
-    - run: python -m pip install "tensorflow>=2.15.0rc0"
-    - run: python -m pip install -v -e .[gpu,test,lmp,cu12] "ase @ https://gitlab.com/ase/ase/-/archive/8c5aa5fd6448c5cfb517a014dccf2b214a9dfa8f/ase-8c5aa5fd6448c5cfb517a014dccf2b214a9dfa8f.tar.gz"
+    - run: python -m pip install "tensorflow>=2.15.0rc0" "torch>=2.2.0"
+    - run: python -m pip install -v -e .[gpu,test,lmp,cu12,torch] "ase @ https://gitlab.com/ase/ase/-/archive/8c5aa5fd6448c5cfb517a014dccf2b214a9dfa8f/ase-8c5aa5fd6448c5cfb517a014dccf2b214a9dfa8f.tar.gz"
       env:
         DP_BUILD_TESTING: 1
         DP_VARIANT: cuda
         CUDA_PATH: /usr/local/cuda-12.2
+        NUM_WORKERS: 0
     - run: dp --version
-    - run: python -m pytest -s --cov=deepmd source/tests --durations=0
+    - run: python -m pytest --cov=deepmd source/tests --durations=0
     - run: source/install/test_cc_local.sh
       env:
         OMP_NUM_THREADS: 1
@@ -57,8 +58,8 @@ jobs:
     - run: |
         export LD_LIBRARY_PATH=$GITHUB_WORKSPACE/dp_test/lib:$CUDA_PATH/lib64:$LD_LIBRARY_PATH
         export PATH=$GITHUB_WORKSPACE/dp_test/bin:$PATH
-        python -m pytest -s --cov=deepmd source/lmp/tests
-        python -m pytest -s --cov=deepmd source/ipi/tests
+        python -m pytest --cov=deepmd source/lmp/tests
+        python -m pytest --cov=deepmd source/ipi/tests
       env:
         OMP_NUM_THREADS: 1
         TF_INTRA_OP_PARALLELISM_THREADS: 1

diff --git a/.github/workflows/test_python.yml b/.github/workflows/test_python.yml
@@ -9,12 +9,12 @@ jobs:
     strategy:
       matrix:
         include:
-          - python: 3.7
-            tf: 1.14
           - python: 3.8
             tf:
+            torch:
           - python: "3.11"
             tf:
+            torch:
 
     steps:
     - uses: actions/checkout@v4
@@ -23,22 +23,25 @@ jobs:
         python-version: ${{ matrix.python }}
         cache: 'pip'
     - uses: mpi4py/setup-mpi@v1
-      if: ${{ matrix.tf == '' }}
       with:
         mpi: openmpi
     # https://github.com/pypa/pip/issues/11770
     - run: python -m pip install -U "pip>=21.3.1,!=23.0.0"
-    - run: pip install -e .[cpu,test]
+    - run: python -m pip install -U "torch==${{ matrix.torch }}" "numpy<1.20"
+      if: matrix.torch != ''
+    - run: pip install -e .[cpu,test,torch]
       env:
         TENSORFLOW_VERSION: ${{ matrix.tf }}
         DP_BUILD_TESTING: 1
     - run: pip install horovod mpi4py
-      if: ${{ matrix.tf == '' }}
       env:
         HOROVOD_WITH_TENSORFLOW: 1
+        HOROVOD_WITHOUT_PYTORCH: 1
         HOROVOD_WITHOUT_GLOO: 1
     - run: dp --version
     - run: pytest --cov=deepmd source/tests --durations=0
+      env:
+        NUM_WORKERS: 0
     - uses: codecov/codecov-action@v3
       with:
         gcov: true

diff --git a/.gitignore b/.gitignore
@@ -13,6 +13,7 @@
 *.bz2
 *.pyc
 *.pb
+*.DS_Store
 tmp*
 CMakeCache.txt
 CMakeFiles

diff --git a/CITATIONS.bib b/CITATIONS.bib
@@ -105,6 +105,25 @@ @misc{Zhang_2022_DPA1
     doi = {10.48550/arXiv.2208.08236},
 }
 
+@misc{Zhang_2023_DPA2,
+    annote = {DPA-2},
+    author = {Duo Zhang and Xinzijian Liu and Xiangyu Zhang and Chengqian Zhang and
+              Chun Cai and Hangrui Bi and Yiming Du and Xuejian Qin and Jiameng Huang
+              and Bowen Li and Yifan Shan and Jinzhe Zeng and Yuzhi Zhang and Siyuan
+              Liu and Yifan Li and Junhan Chang and Xinyan Wang and Shuo Zhou and
+              Jianchuan Liu and Xiaoshan Luo and Zhenyu Wang and Wanrun Jiang and Jing
+              Wu and Yudi Yang and Jiyuan Yang and Manyi Yang and Fu-Qiang Gong and
+              Linshuang Zhang and Mengchao Shi and Fu-Zhi Dai and Darrin M. York and
+              Shi Liu and Tong Zhu and Zhicheng Zhong and Jian Lv and Jun Cheng and
+              Weile Jia and Mohan Chen and Guolin Ke and Weinan E and Linfeng Zhang
+              and Han Wang},
+    title = {{DPA-2: Towards a universal large atomic model for molecular and material
+              simulation}},
+    publisher = {arXiv},
+    year = {2023},
+    doi = {10.48550/arXiv.2312.15492},
+}
+
 @article{Zhang_PhysPlasmas_2020_v27_p122704,
     annote = {frame-specific parameters (e.g. electronic temperature)},
     author = {Zhang, Yuzhi and Gao, Chang and Liu, Qianrui and Zhang, Linfeng and Wang, Han and Chen, Mohan},

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -38,7 +38,7 @@ Currently, we maintain two main branch:
 - devel :  branch for developers
 
 ### Developer guide
-See [here](doc/development/index.md) for coding conventions, API and other needs-to-know of the code.
+See [documentation](https://deepmd.readthedocs.io/) for coding conventions, API and other needs-to-know of the code.
 
 ## How to contribute
 Please perform the following steps to create your Pull Request to this repository. If don't like to use commands, you can also use [GitHub Desktop](https://desktop.github.com/), which is easier to get started. Go to [git documentation](https://git-scm.com/doc) if you want to really master git.

diff --git a/README.md b/README.md
@@ -2,48 +2,28 @@
 
 --------------------------------------------------------------------------------
 
-<span style="font-size:larger;">DeePMD-kit Manual</span>
-========
+# DeePMD-kit
+
 [![GitHub release](https://img.shields.io/github/release/deepmodeling/deepmd-kit.svg?maxAge=86400)](https://github.com/deepmodeling/deepmd-kit/releases)
 [![offline packages](https://img.shields.io/github/downloads/deepmodeling/deepmd-kit/total?label=offline%20packages)](https://github.com/deepmodeling/deepmd-kit/releases)
 [![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)
 [![pip install](https://img.shields.io/pypi/dm/deepmd-kit?label=pip%20install)](https://pypi.org/project/deepmd-kit)
 [![docker pull](https://img.shields.io/docker/pulls/deepmodeling/deepmd-kit)](https://hub.docker.com/r/deepmodeling/deepmd-kit)
 [![Documentation Status](https://readthedocs.org/projects/deepmd/badge/)](https://deepmd.readthedocs.io/)
 
-# Table of contents
-- [About DeePMD-kit](#about-deepmd-kit)
- 	- [Highlights in v2.0](#highlights-in-deepmd-kit-v2.0)
- 	- [Highlighted features](#highlighted-features)
- 	- [License and credits](#license-and-credits)
- 	- [Deep Potential in a nutshell](#deep-potential-in-a-nutshell)
-- [Download and install](#download-and-install)
-- [Use DeePMD-kit](#use-deepmd-kit)
-- [Code structure](#code-structure)
-- [Troubleshooting](#troubleshooting)
-
-# About DeePMD-kit
+## About DeePMD-kit
 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.
 
 For more information, check the [documentation](https://deepmd.readthedocs.io/).
 
-# Highlights in DeePMD-kit v2.0
-* [Model compression](doc/freeze/compress.md). Accelerate the efficiency of model inference 4-15 times.
-* [New descriptors](doc/model/overall.md). Including [`se_e2_r`](doc/model/train-se-e2-r.md) and [`se_e3`](doc/model/train-se-e3.md).
-* [Hybridization of descriptors](doc/model/train-hybrid.md). Hybrid descriptor constructed from the concatenation of several descriptors.
-* [Atom type embedding](doc/model/train-se-e2-a-tebd.md). 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.
-
-## Highlighted features
-* **interfaced with TensorFlow**, one of the most popular deep learning frameworks, making the training process highly automatic and efficient, in addition, Tensorboard can be used to visualize training procedures.
-* **interfaced with high-performance classical MD and quantum (path-integral) MD packages**, i.e., LAMMPS and i-PI, respectively.
-* **implements the Deep Potential series models**, which have been successfully applied to finite and extended systems including organic molecules, metals, semiconductors, insulators, etc.
+### Highlighted features
+* **interfaced with multiple backends**, including TensorFlow and PyTorch, 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 ABUCUS.
+* **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.
 
-## License and credits
+### License and credits
 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:
 - 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.
@@ -55,7 +35,9 @@ If you use this code in any future publications, please cite the following publi
 
 In addition, please follow [the bib file](CITATIONS.bib) to cite the methods you used.
 
-## Deep Potential in a nutshell
+### Highlights in major versions
+
+#### Initial version
 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.
 
 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.
@@ -64,116 +46,53 @@ Although highly efficient, the original Deep Potential model satisfies the exten
 
 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.
 
-See [our latest paper](https://doi.org/10.48550/arXiv.2304.09409) for details of all features.
-
-# Download and install
-
-Please follow our [GitHub](https://github.com/deepmodeling/deepmd-kit) webpage to download the [latest released version](https://github.com/deepmodeling/deepmd-kit/tree/master) and [development version](https://github.com/deepmodeling/deepmd-kit/tree/devel).
-
-DeePMD-kit offers multiple installation methods. It is recommended to use easy methods like [offline packages](doc/install/easy-install.md#offline-packages), [conda](doc/install/easy-install.md#with-conda) and [docker](doc/install/easy-install.md#with-docker).
-
-One may manually install DeePMD-kit by following the instructions on [installing the Python interface](doc/install/install-from-source.md#install-the-python-interface) and [installing the C++ interface](doc/install/install-from-source.md#install-the-c-interface). The C++ interface is necessary when using DeePMD-kit with LAMMPS, i-PI or GROMACS.
-
-
-# Use DeePMD-kit
-
-A quick start on using DeePMD-kit can be found [here](doc/getting-started/quick_start.ipynb).
-
-A full [document](doc/train/train-input-auto.rst) on options in the training input script is available.
-
-# Advanced
-
-- [Installation](doc/install/index.md)
-    - [Easy install](doc/install/easy-install.md)
-    - [Install from source code](doc/install/install-from-source.md)
-    - [Install from pre-compiled C library](doc/install/install-from-c-library.md)
-    - [Install LAMMPS](doc/install/install-lammps.md)
-    - [Install i-PI](doc/install/install-ipi.md)
-    - [Install GROMACS](doc/install/install-gromacs.md)
-    - [Building conda packages](doc/install/build-conda.md)
-    - [Install Node.js interface](doc/install/install-nodejs.md)
-    - [Easy install the latest development version](doc/install/easy-install-dev.md)
-- [Data](doc/data/index.md)
-    - [System](doc/data/system.md)
-    - [Formats of a system](doc/data/data-conv.md)
-    - [Prepare data with dpdata](doc/data/dpdata.md)
-- [Model](doc/model/index.md)
-    - [Overall](doc/model/overall.md)
-    - [Descriptor `"se_e2_a"`](doc/model/train-se-e2-a.md)
-    - [Descriptor `"se_e2_r"`](doc/model/train-se-e2-r.md)
-    - [Descriptor `"se_e3"`](doc/model/train-se-e3.md)
-    - [Descriptor `"se_atten"`](doc/model/train-se-atten.md)
-    - [Descriptor `"se_atten_v2"`](doc/model/train-se-atten.md#descriptor-se_atten_v2)
-    - [Descriptor `"hybrid"`](doc/model/train-hybrid.md)
-    - [Descriptor `sel`](doc/model/sel.md)
-    - [Fit energy](doc/model/train-energy.md)
-    - [Fit spin energy](doc/model/train-energy-spin.md)
-    - [Fit `tensor` like `Dipole` and `Polarizability`](doc/model/train-fitting-tensor.md)
-    - [Fit electronic density of states (DOS)](doc/model/train-fitting-dos.md)
-    - [Train a Deep Potential model using `type embedding` approach](doc/model/train-se-e2-a-tebd.md)
-    - [Deep potential long-range](doc/model/dplr.md)
-    - [Deep Potential - Range Correction (DPRc)](doc/model/dprc.md)
-    - [Linear model](doc/model/linear.md)
-    - [Interpolation or combination with a pairwise potential](doc/model/pairtab.md)
-- [Training](doc/train/index.md)
-    - [Training a model](doc/train/training.md)
-    - [Advanced options](doc/train/training-advanced.md)
-    - [Parallel training](doc/train/parallel-training.md)
-    - [Multi-task training](doc/train/multi-task-training.md)
-    - [TensorBoard Usage](doc/train/tensorboard.md)
-    - [Known limitations of using GPUs](doc/train/gpu-limitations.md)
-    - [Training Parameters](doc/train-input-auto.rst)
-- [Freeze and Compress](doc/freeze/index.rst)
-    - [Freeze a model](doc/freeze/freeze.md)
-    - [Compress a model](doc/freeze/compress.md)
-- [Test](doc/test/index.rst)
-    - [Test a model](doc/test/test.md)
-    - [Calculate Model Deviation](doc/test/model-deviation.md)
-- [Inference](doc/inference/index.rst)
-    - [Python interface](doc/inference/python.md)
-    - [C++ interface](doc/inference/cxx.md)
-    - [Node.js interface](doc/inference/nodejs.md)
-- [Integrate with third-party packages](doc/third-party/index.rst)
-    - [Use deep potential with dpdata](doc/third-party/dpdata.md)
-    - [Use deep potential with ASE](doc/third-party/ase.md)
-    - [Run MD with LAMMPS](doc/third-party/lammps-command.md)
-    - [Run path-integral MD with i-PI](doc/third-party/ipi.md)
-    - [Run MD with GROMACS](doc/third-party/gromacs.md)
-    - [Interfaces out of DeePMD-kit](doc/third-party/out-of-deepmd-kit.md)
-- [Use NVNMD](doc/nvnmd/index.md)
-
-# Code structure
+#### v1
+
+* Code refactor to make it highly modularized.
+* GPU support for descriptors.
+
+#### v2
+
+* 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.
+
+See [our latest paper](https://doi.org/10.1063/5.0155600) for details of all features until v2.2.3.
+
+#### v3
+
+* Multiple backends supported. Add a PyTorch backend.
+* The DPA-2 model.
+
+## Install and use DeePMD-kit
+
+Please read the [online documentation](https://deepmd.readthedocs.io/) for how to install and use DeePMD-kit.
+
+## Code structure
 
 The code is organized as follows:
 
-* `data/raw`: tools manipulating the raw data files.
 * `examples`: examples.
 * `deepmd`: DeePMD-kit python modules.
+* `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/lib`: source code of DeePMD-kit library.
 * `source/lmp`: source code of Lammps module.
 * `source/gmx`: source code of Gromacs plugin.
-* `source/op`: TensorFlow op implementation. working with the library.
-
-
-# Troubleshooting
-
-- [Model compatibility](doc/troubleshooting/model_compatability.md)
-- [Installation](doc/troubleshooting/installation.md)
-- [The temperature undulates violently during the early stages of MD](doc/troubleshooting/md_energy_undulation.md)
-- [MD: cannot run LAMMPS after installing a new version of DeePMD-kit](doc/troubleshooting/md_version_compatibility.md)
-- [Do we need to set rcut < half boxsize?](doc/troubleshooting/howtoset_rcut.md)
-- [How to set sel?](doc/troubleshooting/howtoset_sel.md)
-- [How to control the parallelism of a job?](doc/troubleshooting/howtoset_num_nodes.md)
-- [How to tune Fitting/embedding-net size?](doc/troubleshooting/howtoset_netsize.md)
-- [Why does a model have low precision?](doc/troubleshooting/precision.md)
 
 # Contributing
 
 See [DeePMD-kit Contributing Guide](CONTRIBUTING.md) to become a contributor! 🤓
 
-
 [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

diff --git a/backend/dynamic_metadata.py b/backend/dynamic_metadata.py
@@ -46,6 +46,7 @@ def dynamic_metadata(
                 "sphinx_markdown_tables",
                 "myst-nb>=1.0.0rc0",
                 "myst-parser>=0.19.2",
+                "sphinx-design",
                 "breathe",
                 "exhale",
                 "numpydoc",
@@ -88,4 +89,7 @@ def dynamic_metadata(
                 "nvidia-cudnn-cu12",
                 "nvidia-cuda-nvcc-cu12",
             ],
+            "torch": [
+                "torch>=2a",
+            ],
         }
-Original file line number
+Diff line change
@@ Expand Up / @@ -13,6 +13,7 @@ @@
     *.bz2
     *.pyc
     *.pb
+    *.DS_Store
     tmp*
     CMakeCache.txt
     CMakeFiles
@@ Expand Down @@