diff --git a/.github/labeler.yml b/.github/labeler.yml index bca580cfea..b048574e77 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -1,38 +1,38 @@ -Python: -- changed-files: - - any-glob-to-any-file: - - deepmd/**/* - - source/tests/**/* -Docs: -- changed-files: - - any-glob-to-any-file: doc/**/* -Examples: -- changed-files: - - any-glob-to-any-file: examples/**/* -Core: -- changed-files: - - any-glob-to-any-file: source/lib/**/* -CUDA: -- changed-files: - - any-glob-to-any-file: source/lib/src/gpu/**/* -ROCM: -- changed-files: - - any-glob-to-any-file: source/lib/src/gpu/**/* -OP: -- changed-files: - - any-glob-to-any-file: source/op/**/* -C++: -- changed-files: - - any-glob-to-any-file: source/api_cc/**/* -C: -- changed-files: - - any-glob-to-any-file: source/api_c/**/* -LAMMPS: -- changed-files: - - any-glob-to-any-file: source/lmp/**/* -Gromacs: -- changed-files: - - any-glob-to-any-file: source/gmx/**/* -i-Pi: -- changed-files: - - any-glob-to-any-file: source/ipi/**/* +Python: + - changed-files: + - any-glob-to-any-file: + - deepmd/**/* + - source/tests/**/* +Docs: + - changed-files: + - any-glob-to-any-file: doc/**/* +Examples: + - changed-files: + - any-glob-to-any-file: examples/**/* +Core: + - changed-files: + - any-glob-to-any-file: source/lib/**/* +CUDA: + - changed-files: + - any-glob-to-any-file: source/lib/src/gpu/**/* +ROCM: + - changed-files: + - any-glob-to-any-file: source/lib/src/gpu/**/* +OP: + - changed-files: + - any-glob-to-any-file: source/op/**/* +C++: + - changed-files: + - any-glob-to-any-file: source/api_cc/**/* +C: + - changed-files: + - any-glob-to-any-file: source/api_c/**/* +LAMMPS: + - changed-files: + - any-glob-to-any-file: source/lmp/**/* +Gromacs: + - changed-files: + - any-glob-to-any-file: source/gmx/**/* +i-Pi: + - changed-files: + - any-glob-to-any-file: source/ipi/**/* diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 1860f87fea..8e147fc2c4 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,118 +1,121 @@ # See https://pre-commit.com for more information # See https://pre-commit.com/hooks.html for more hooks repos: -- repo: https://github.com/pre-commit/pre-commit-hooks + - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.5.0 hooks: - - id: trailing-whitespace + - id: trailing-whitespace exclude: "^.+\\.pbtxt$" - - id: end-of-file-fixer + - id: end-of-file-fixer exclude: "^.+\\.pbtxt$" - - id: check-yaml - - id: check-json - - id: check-added-large-files - args: ['--maxkb=1024', '--enforce-all'] + - id: check-yaml + - id: check-json + - id: check-added-large-files + args: ["--maxkb=1024", "--enforce-all"] exclude: | - (?x)^( - source/tests/infer/dipolecharge_e.pbtxt| - source/tests/infer/deeppolar_new.pbtxt - )$ - - id: check-merge-conflict - - id: check-symlinks - - id: check-toml -# Python -- repo: https://github.com/PyCQA/isort + (?x)^( + source/tests/infer/dipolecharge_e.pbtxt| + source/tests/infer/deeppolar_new.pbtxt + )$ + - id: check-merge-conflict + - id: check-symlinks + - id: check-toml + # Python + - repo: https://github.com/PyCQA/isort rev: 5.13.2 hooks: - - id: isort - files: \.py$ - exclude: ^source/3rdparty -- repo: https://github.com/astral-sh/ruff-pre-commit + - id: isort + files: \.py$ + exclude: ^source/3rdparty + - repo: https://github.com/astral-sh/ruff-pre-commit # Ruff version. rev: v0.3.3 hooks: - - id: ruff - args: ["--fix"] - exclude: ^source/3rdparty - types_or: [python, pyi, jupyter] - - id: ruff-format - exclude: ^source/3rdparty - types_or: [python, pyi, jupyter] -# numpydoc -- repo: https://github.com/Carreau/velin + - id: ruff + args: ["--fix"] + exclude: ^source/3rdparty + types_or: [python, pyi, jupyter] + - id: ruff-format + exclude: ^source/3rdparty + types_or: [python, pyi, jupyter] + # numpydoc + - repo: https://github.com/Carreau/velin rev: 0.0.12 hooks: - - id: velin - args: ["--write"] - exclude: ^source/3rdparty -# Python inside docs -- repo: https://github.com/asottile/blacken-docs + - id: velin + args: ["--write"] + exclude: ^source/3rdparty + # Python inside docs + - repo: https://github.com/asottile/blacken-docs rev: 1.16.0 hooks: - - id: blacken-docs -# C++ -- repo: https://github.com/pre-commit/mirrors-clang-format + - id: blacken-docs + # C++ + - repo: https://github.com/pre-commit/mirrors-clang-format rev: v18.1.1 hooks: - - id: clang-format + - id: clang-format exclude: ^source/3rdparty|source/lib/src/gpu/cudart/.+\.inc -# CSS -- repo: https://github.com/pre-commit/mirrors-csslint - rev: v1.0.5 + # markdown, yaml, CSS, javascript + - repo: https://github.com/pre-commit/mirrors-prettier + rev: v4.0.0-alpha.8 + hooks: + - id: prettier + types_or: [markdown, yaml, css] + # workflow files cannot be modified by pre-commit.ci + exclude: ^(source/3rdparty|\.github/workflows|\.clang-format) + # Shell + - repo: https://github.com/scop/pre-commit-shfmt + rev: v3.8.0-1 + hooks: + - id: shfmt + # CMake + - repo: https://github.com/cheshirekow/cmake-format-precommit + rev: v0.6.13 + hooks: + - id: cmake-format + #- id: cmake-lint + # license header + - repo: https://github.com/Lucas-C/pre-commit-hooks + rev: v1.5.5 hooks: - - id: csslint -# Shell -- repo: https://github.com/scop/pre-commit-shfmt - rev: v3.8.0-1 - hooks: - - id: shfmt -# CMake -- repo: https://github.com/cheshirekow/cmake-format-precommit - rev: v0.6.13 - hooks: - - id: cmake-format - #- id: cmake-lint -# license header -- repo: https://github.com/Lucas-C/pre-commit-hooks - rev: v1.5.5 - hooks: - # C++, js - - id: insert-license + # C++, js + - id: insert-license files: \.(c|cc|cpp|js|ts|h|hpp)$ args: - - --license-filepath - - .license-header.txt - - --comment-style - - // - - --no-extra-eol + - --license-filepath + - .license-header.txt + - --comment-style + - // + - --no-extra-eol exclude: ^source/3rdparty|source/lib/src/gpu/cudart/.+\.inc - # CSS - - id: insert-license + # CSS + - id: insert-license files: \.(css|scss)$ args: - - --license-filepath - - .license-header.txt - - --comment-style - - /*| *| */ - - --no-extra-eol - # Python - - id: insert-license + - --license-filepath + - .license-header.txt + - --comment-style + - /*| *| */ + - --no-extra-eol + # Python + - id: insert-license files: \.(py|pyx)$ args: - - --license-filepath - - .license-header.txt - - --comment-style - - "#" - - --no-extra-eol + - --license-filepath + - .license-header.txt + - --comment-style + - "#" + - --no-extra-eol exclude: ^source/3rdparty - # HTML - - id: insert-license + # HTML + - id: insert-license files: \.(html|vue|xml)$ args: - - --license-filepath - - .license-header.txt - - --comment-style - - - - --no-extra-eol + - --license-filepath + - .license-header.txt + - --comment-style + - + - --no-extra-eol ci: autoupdate_branch: devel diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f2c28ae59b..cb08609c2b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,6 +7,7 @@ Welcome to [DeePMD-kit](https://github.com/deepmodeling/deepmd-kit)! You can either make a code contribution, help improve our document or offer help to other users. Your help is always appreciated. Come and have fun! ### Code contribution + You can start from any one of the following items to help improve deepmd-kit - Smash a bug @@ -18,6 +19,7 @@ See [here](#before-you-contribute) for some before-hand heads-up. See [here](#how-to-contribute) to learn how to contribute. ### Document improvement + You can start from any one of the following items to help improve [DeePMD-kit Docs](https://deepmd.readthedocs.io/en/latest/?badge=latest): - Fix typos or format (punctuation, space, indentation, code block, etc.) @@ -26,21 +28,27 @@ You can start from any one of the following items to help improve [DeePMD-kit Do - Translate docs changes from English to Chinese ### Offer help + You can help other users of deepmd-kit in the following way - Submit, reply to, and resolve [issues](https://github.com/deepmodeling/deepmd-kit/issues) - (Advanced) Review Pull Requests created by others ## Before you contribute + ### Overview of DeePMD-kit + Currently, we maintain two main branch: + - master: stable branch with version tag -- devel : branch for developers +- devel : branch for developers ### Developer guide + 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. ### Step 1: Fork the repository @@ -51,79 +59,82 @@ Please perform the following steps to create your Pull Request to this repositor ### Step 2: Clone the forked repository to local storage and set configurations 1. Clone your own repo, not the public repo (from deepmodeling) ! And change the branch to devel. - ```bash - git clone https://github.com/$username/deepmd-kit.git - # Replace `$username` with your GitHub ID - git checkout devel - ``` + ```bash + git clone https://github.com/$username/deepmd-kit.git + # Replace `$username` with your GitHub ID + + git checkout devel + ``` 2. Add deepmodeling's repo as your remote repo, we can name it "upstream". And fetch upstream's latest codes to your workstation. - ```bash - git remote add upstream https://github.com/deepmodeling/deepmd-kit.git - # After you add a remote repo, your local repo will be automatically named "origin". - git fetch upstream + ```bash + git remote add upstream https://github.com/deepmodeling/deepmd-kit.git + # After you add a remote repo, your local repo will be automatically named "origin". - # If your current codes are behind the latest codes, you should merge latest codes first. - # Notice you should merge from "devel"! - git merge upstream/devel - ``` + git fetch upstream + + # If your current codes are behind the latest codes, you should merge latest codes first. + # Notice you should merge from "devel"! + git merge upstream/devel + ``` 3. Modify your codes and design unit tests. 4. Commit your changes - ```bash - git status # Checks the local status - git add ... # Adds the file(s) you want to commit. If you want to commit all changes, you can directly use `git add.` - git commit -m "commit-message: update the xx" - ``` + + ```bash + git status # Checks the local status + git add ... # Adds the file(s) you want to commit. If you want to commit all changes, you can directly use `git add.` + git commit -m "commit-message: update the xx" + ``` 5. Push the changed codes to your original repo on github. - ```bash - git push origin devel - ``` + ```bash + git push origin devel + ``` ### Alternatively: Create a new branch 1. Get your local master up-to-date with upstream/master. - ```bash - cd $working_dir/deepmd-kit - git fetch upstream - git checkout master - git rebase upstream/master - ``` + ```bash + cd $working_dir/deepmd-kit + git fetch upstream + git checkout master + git rebase upstream/master + ``` 2. Create a new branch based on the master branch. - ```bash - git checkout -b new-branch-name - ``` + ```bash + git checkout -b new-branch-name + ``` 3. Modify your codes and design unit tests. 4. Commit your changes - ```bash - git status # Checks the local status - git add ... # Adds the file(s) you want to commit. If you want to commit all changes, you can directly use `git add.` - git commit -m "commit-message: update the xx" - ``` + ```bash + git status # Checks the local status + git add ... # Adds the file(s) you want to commit. If you want to commit all changes, you can directly use `git add.` + git commit -m "commit-message: update the xx" + ``` 5. Keep your branch in sync with upstream/master - ```bash - # While on your new branch - git fetch upstream - git rebase upstream/master - ``` + ```bash + # While on your new branch + git fetch upstream + git rebase upstream/master + ``` 6. Push your changes to the remote - ```bash - git push -u origin new-branch-name # "-u" is used to track the remote branch from origin - ``` + ```bash + git push -u origin new-branch-name # "-u" is used to track the remote branch from origin + ``` ### Step 3: Create a pull request @@ -133,4 +144,5 @@ Please perform the following steps to create your Pull Request to this repositor Now, your PR is successfully submitted! After this PR is merged, you will automatically become a contributor to DeePMD-kit. ## Contact us + E-mail: contact@deepmodeling.org diff --git a/README.md b/README.md index 2076e11f1b..3838f2596a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ [DeePMD-kit logo](./doc/logo.md) --------------------------------------------------------------------------------- +--- # DeePMD-kit @@ -12,35 +12,40 @@ [![Documentation Status](https://readthedocs.org/projects/deepmd/badge/)](https://deepmd.readthedocs.io/) ## 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/). ### 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. + +- **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 + 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. -[![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) -[![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) + [![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) + [![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) - 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. -[![doi:10.1063/5.0155600](https://img.shields.io/badge/DOI-10.1063%2F5.0155600-blue)](https://doi.org/10.1063/5.0155600) -[![Citations](https://citations.njzjz.win/10.1063/5.0155600)](https://badge.dimensions.ai/details/doi/10.1063/5.0155600) + [![doi:10.1063/5.0155600](https://img.shields.io/badge/DOI-10.1063%2F5.0155600-blue)](https://doi.org/10.1063/5.0155600) + [![Citations](https://citations.njzjz.win/10.1063/5.0155600)](https://badge.dimensions.ai/details/doi/10.1063/5.0155600) In addition, please follow [the bib file](CITATIONS.bib) to cite the methods you used. ### 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. +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. 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. @@ -48,27 +53,27 @@ In addition to building up potential energy models, DeePMD-kit can also be used #### v1 -* Code refactor to make it highly modularized. -* GPU support for descriptors. +- 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. +- 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. +- Multiple backends supported. Add a PyTorch backend. +- The DPA-2 model. ## Install and use DeePMD-kit @@ -78,16 +83,16 @@ Please read the [online documentation](https://deepmd.readthedocs.io/) for how t The code is organized as follows: -* `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/lmp`: source code of Lammps module. -* `source/gmx`: source code of Gromacs plugin. +- `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/lmp`: source code of Lammps module. +- `source/gmx`: source code of Gromacs plugin. # Contributing diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css index 8894f47813..d0b761e71d 100644 --- a/doc/_static/css/custom.css +++ b/doc/_static/css/custom.css @@ -1,20 +1,22 @@ /* * SPDX-License-Identifier: LGPL-3.0-or-later */ -pre{ - overflow: auto; +pre { + overflow: auto; } -.wy-side-nav-search .wy-dropdown > a img.logo, .wy-side-nav-search > a img.logo { - width: 275px; +.wy-side-nav-search .wy-dropdown > a img.logo, +.wy-side-nav-search > a img.logo { + width: 275px; } img.platform-icon { - height: 2ex; + height: 2ex; } @media (prefers-color-scheme: dark) { - .wy-side-nav-search .wy-dropdown > a img.logo, .wy-side-nav-search > a img.logo { - content: url("../logo-dark.svg"); - } - img.platform-icon { - filter: invert(1); - } + .wy-side-nav-search .wy-dropdown > a img.logo, + .wy-side-nav-search > a img.logo { + content: url("../logo-dark.svg"); + } + img.platform-icon { + filter: invert(1); + } } diff --git a/doc/data/data-conv.md b/doc/data/data-conv.md index e8464b1ea9..7634daf5e6 100644 --- a/doc/data/data-conv.md +++ b/doc/data/data-conv.md @@ -5,6 +5,7 @@ Two binary formats, NumPy and HDF5, are supported for training. The raw format i ## NumPy format In a system with the Numpy format, the system properties are stored as text files ending with `.raw`, such as `type.raw` and `type_map.raw`, under the system directory. If one needs to train a non-periodic system, an empty `nopbc` file should be put under the system directory. Both input and labeled frame properties are saved as the [NumPy binary data (NPY) files](https://numpy.org/doc/stable/reference/generated/numpy.lib.format.html#npy-format) ending with `.npy` in each of the `set.*` directories. Take an example, a system may contain the following files: + ``` type.raw type_map.raw @@ -18,16 +19,19 @@ set.001/force.npy ``` We assume that the atom types do not change in all frames. It is provided by `type.raw`, which has one line with the types of atoms written one by one. The atom types should be integers. For example the `type.raw` of a system that has 2 atoms with 0 and 1: + ```bash $ cat type.raw 0 1 ``` Sometimes one needs to map the integer types to atom names. The mapping can be given by the file `type_map.raw`. For example + ```bash $ cat type_map.raw O H ``` + The type `0` is named by `"O"` and the type `1` is named by `"H"`. For training models with descriptor `se_atten`, a [new system format](../model/train-se-atten.md#data-format) is supported to put together the frame-sparse systems with the same atom number. @@ -35,9 +39,11 @@ For training models with descriptor `se_atten`, a [new system format](../model/t ## HDF5 format A system with the HDF5 format has the same structure as the Numpy format, but in an HDF5 file, a system is organized as an [HDF5 group](https://docs.h5py.org/en/stable/high/group.html). The file name of a Numpy file is the key in an HDF5 file, and the data is the value of the key. One needs to use `#` in a DP path to divide the path to the HDF5 file and the HDF5 path: + ``` /path/to/data.hdf5#/H2O ``` + Here, `/path/to/data.hdf5` is the file path and `/H2O` is the HDF5 path. All HDF5 paths should start with `/`. There should be some data in the `H2O` group, such as `/H2O/type.raw` and `/H2O/set.000/force.npy`. An HDF5 file with a large number of systems has better performance than multiple NumPy files in a large cluster. @@ -47,15 +53,18 @@ An HDF5 file with a large number of systems has better performance than multiple A raw file is a plain text file with each information item written in one file and one frame written on one line. **It's not directly supported**, but we provide a tool to convert them. In the raw format, the property of one frame is provided per line, ending with `.raw`. Take an example, the default files that provide box, coordinate, force, energy and virial are `box.raw`, `coord.raw`, `force.raw`, `energy.raw` and `virial.raw`, respectively. Here is an example of `force.raw`: + ```bash $ cat force.raw -0.724 2.039 -0.951 0.841 -0.464 0.363 6.737 1.554 -5.587 -2.803 0.062 2.222 -1.968 -0.163 1.020 -0.225 -0.789 0.343 ``` + This `force.raw` contains 3 frames with each frame having the forces of 2 atoms, thus it has 3 lines and 6 columns. Each line provides all the 3 force components of 2 atoms in 1 frame. The first three numbers are the 3 force components of the first atom, while the second three numbers are the 3 force components of the second atom. Other files are organized similarly. The number of lines of all raw files should be identical. One can use the script `$deepmd_source_dir/data/raw/raw_to_set.sh` to convert the prepared raw files to the NumPy format. For example, if we have a raw file that contains 6000 frames, + ```bash $ ls box.raw coord.raw energy.raw force.raw type.raw virial.raw @@ -69,4 +78,5 @@ making set 2 ... $ ls box.raw coord.raw energy.raw force.raw set.000 set.001 set.002 type.raw virial.raw ``` + It generates three sets `set.000`, `set.001` and `set.002`, with each set containing 2000 frames in the Numpy format. diff --git a/doc/data/dpdata.md b/doc/data/dpdata.md index 9b1a27ce82..63fe4f39c3 100644 --- a/doc/data/dpdata.md +++ b/doc/data/dpdata.md @@ -3,16 +3,19 @@ One can use a convenient tool [`dpdata`](https://github.com/deepmodeling/dpdata) to convert data directly from the output of first principle packages to the DeePMD-kit format. To install one can execute + ```bash pip install dpdata ``` An example of converting data [VASP](https://www.vasp.at/) data in `OUTCAR` format to DeePMD-kit data can be found at + ``` $deepmd_source_dir/examples/data_conv ``` Switch to that directory, then one can convert data by using the following python script + ```python import dpdata diff --git a/doc/data/system.md b/doc/data/system.md index 0ecd0e9119..6ca044f1c9 100644 --- a/doc/data/system.md +++ b/doc/data/system.md @@ -4,44 +4,44 @@ DeePMD-kit takes a **system** as the data structure. A snapshot of a system is c A system should contain system properties, input frame properties, and labeled frame properties. The system property contains the following property: -ID | Property | Raw file | Required/Optional | Shape | Description --------- | ---------------------- | ------------ | -------------------- | ----------------------- | ----------- -type | Atom type indexes | type.raw | Required | Natoms | Integers that start with 0. If both the training parameter {ref}`type_map ` is set and `type_map.raw` is provided, the system atom type should be mapped to `type_map.raw` in `type.raw` and will be mapped to the model atom type when training; otherwise, the system atom type will be always mapped to the model atom type (whether {ref}`type_map ` is set or not) -type_map | Atom type names | type_map.raw | Optional | Ntypes | Atom names that map to atom type, which is unnecessary to be contained in the periodic table. Only works when the training parameter {ref}`type_map ` is set -nopbc | Non-periodic system | nopbc | Optional | 1 | If True, this system is non-periodic; otherwise it's periodic +| ID | Property | Raw file | Required/Optional | Shape | Description | +| -------- | ------------------- | ------------ | ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| type | Atom type indexes | type.raw | Required | Natoms | Integers that start with 0. If both the training parameter {ref}`type_map ` is set and `type_map.raw` is provided, the system atom type should be mapped to `type_map.raw` in `type.raw` and will be mapped to the model atom type when training; otherwise, the system atom type will be always mapped to the model atom type (whether {ref}`type_map ` is set or not) | +| type_map | Atom type names | type_map.raw | Optional | Ntypes | Atom names that map to atom type, which is unnecessary to be contained in the periodic table. Only works when the training parameter {ref}`type_map ` is set | +| nopbc | Non-periodic system | nopbc | Optional | 1 | If True, this system is non-periodic; otherwise it's periodic | The input frame properties contain the following property, the first axis of which is the number of frames: -ID | Property | Raw file | Unit | Required/Optional | Shape | Description --------- | ---------------------- | -------------- | ---- | -------------------- | ----------------------- | ----------- -coord | Atomic coordinates | coord.raw | Å | Required | Nframes \* Natoms \* 3 | -box | Boxes | box.raw | Å | Required if periodic | Nframes \* 3 \* 3 | in the order `XX XY XZ YX YY YZ ZX ZY ZZ` -fparam | Extra frame parameters | fparam.raw | Any | Optional | Nframes \* Any | -aparam | Extra atomic parameters | aparam.raw | Any | Optional | Nframes \* aparam \* Any | -numb_copy | Each frame is copied by the `numb_copy` (int) times | prob.raw | 1 | Optional | Nframes | Integer; Default is 1 for all frames +| ID | Property | Raw file | Unit | Required/Optional | Shape | Description | +| --------- | --------------------------------------------------- | ---------- | ---- | -------------------- | ------------------------ | ----------------------------------------- | +| coord | Atomic coordinates | coord.raw | Å | Required | Nframes \* Natoms \* 3 | +| box | Boxes | box.raw | Å | Required if periodic | Nframes \* 3 \* 3 | in the order `XX XY XZ YX YY YZ ZX ZY ZZ` | +| fparam | Extra frame parameters | fparam.raw | Any | Optional | Nframes \* Any | +| aparam | Extra atomic parameters | aparam.raw | Any | Optional | Nframes \* aparam \* Any | +| numb_copy | Each frame is copied by the `numb_copy` (int) times | prob.raw | 1 | Optional | Nframes | Integer; Default is 1 for all frames | The labeled frame properties are listed as follows, all of which will be used for training if and only if the loss function contains such property: -ID | Property | Raw file | Unit | Shape | Description ----------------------- | ----------------------- | ------------------------ | ---- | ----------------------- | ----------- -energy | Frame energies | energy.raw | eV | Nframes | -force | Atomic forces | force.raw | eV/Å | Nframes \* Natoms \* 3 | -virial | Frame virial | virial.raw | eV | Nframes \* 9 | in the order `XX XY XZ YX YY YZ ZX ZY ZZ` -atom_ener | Atomic energies | atom_ener.raw | eV | Nframes \* Natoms | -atom_pref | Weights of atomic forces | atom_pref.raw | 1 | Nframes \* Natoms | -dipole | Frame dipole | dipole.raw | Any | Nframes \* 3 | -atomic_dipole | Atomic dipole | atomic_dipole.raw | Any | Nframes \* Natoms \* 3 | -polarizability | Frame polarizability | polarizability.raw | Any | Nframes \* 9 | in the order `XX XY XZ YX YY YZ ZX ZY ZZ` -atomic_polarizability | Atomic polarizability | atomic_polarizability.raw| Any | Nframes \* Natoms \* 9 | in the order `XX XY XZ YX YY YZ ZX ZY ZZ` -drdq | Partial derivative of atomic coordinates with respect to generalized coordinates | drdq.raw | 1 | Nframes \* Natoms \* 3 \* Ngen_coords | +| ID | Property | Raw file | Unit | Shape | Description | +| --------------------- | -------------------------------------------------------------------------------- | ------------------------- | ---- | ------------------------------------- | ----------------------------------------- | +| energy | Frame energies | energy.raw | eV | Nframes | +| force | Atomic forces | force.raw | eV/Å | Nframes \* Natoms \* 3 | +| virial | Frame virial | virial.raw | eV | Nframes \* 9 | in the order `XX XY XZ YX YY YZ ZX ZY ZZ` | +| atom_ener | Atomic energies | atom_ener.raw | eV | Nframes \* Natoms | +| atom_pref | Weights of atomic forces | atom_pref.raw | 1 | Nframes \* Natoms | +| dipole | Frame dipole | dipole.raw | Any | Nframes \* 3 | +| atomic_dipole | Atomic dipole | atomic_dipole.raw | Any | Nframes \* Natoms \* 3 | +| polarizability | Frame polarizability | polarizability.raw | Any | Nframes \* 9 | in the order `XX XY XZ YX YY YZ ZX ZY ZZ` | +| atomic_polarizability | Atomic polarizability | atomic_polarizability.raw | Any | Nframes \* Natoms \* 9 | in the order `XX XY XZ YX YY YZ ZX ZY ZZ` | +| drdq | Partial derivative of atomic coordinates with respect to generalized coordinates | drdq.raw | 1 | Nframes \* Natoms \* 3 \* Ngen_coords | In general, we always use the following convention of units: -Property | Unit ----------| ---- -Time | ps -Length | Å -Energy | eV -Force | eV/Å -Virial | eV -Pressure | Bar +| Property | Unit | +| -------- | ---- | +| Time | ps | +| Length | Å | +| Energy | eV | +| Force | eV/Å | +| Virial | eV | +| Pressure | Bar | diff --git a/doc/development/cmake.md b/doc/development/cmake.md index 3073327856..f8508d8992 100644 --- a/doc/development/cmake.md +++ b/doc/development/cmake.md @@ -9,11 +9,13 @@ find_package(DeePMD REQUIRED) Note that you may need to add ${deepmd_root} to the cached CMake variable `CMAKE_PREFIX_PATH`. To link against the C interface library, using + ```cmake target_link_libraries(some_library PRIVATE DeePMD::deepmd_c) ``` To link against the C++ interface library, using + ```cmake target_link_libraries(some_library PRIVATE DeePMD::deepmd_cc) ``` diff --git a/doc/development/create-a-model-pt.md b/doc/development/create-a-model-pt.md index 6fcddd33d8..35d81b364a 100644 --- a/doc/development/create-a-model-pt.md +++ b/doc/development/create-a-model-pt.md @@ -3,6 +3,7 @@ If you'd like to create a new model that isn't covered by the existing DeePMD-kit library, but reuse DeePMD-kit's other efficient modules such as data processing, trainner, etc, you may want to read this section. To incorporate your custom model you'll need to: + 1. Register and implement new components (e.g. descriptor) in a Python file. 2. Register new arguments for user inputs. 3. Package new codes into a Python package. @@ -72,7 +73,6 @@ The serialize and deserialize methods are important for cross-backend model conv In many instances, there is no requirement to create a new fitting net. For fitting user-defined scalar properties, the {py:class}`deepmd.pt.model.task.ener.InvarFitting` class can be utilized. However, if there is a need for a new fitting net, one should inherit from both the {py:class}`deepmd.pt.model.task.base_fitting.BaseFitting` class and the {py:class}`torch.nn.Module` class. Alternatively, for a more straightforward approach, inheritance from the {py:class}`deepmd.pt.model.task.fitting.GeneralFitting` class is also an option. - ```py from deepmd.pt.model.task.fitting import ( GeneralFitting, @@ -104,10 +104,12 @@ class SomeFittingNet(GeneralFitting): def output_def(self) -> FittingOutputDef: pass ``` + ### New models + The PyTorch backend's model architecture is meticulously structured with multiple layers of abstraction, ensuring a high degree of flexibility. Typically, the process commences with an atomic model responsible for atom-wise property calculations. This atomic model inherits from both the {py:class}`deepmd.pt.model.atomic_model.base_atomic_model.BaseAtomicModel` class and the {py:class}`torch.nn.Module` class. -Subsequently, the `AtomicModel` is encapsulated using the `make_model(AtomicModel)` function, which leverages the `deepmd.pt.model.model.make_model.make_model` function. The purpose of the `make_model` wrapper is to facilitate the translation between atomic property predictions and the extended property predictions and differentiation , e.g. the reduction of atomic energy contribution and the autodiff for calculating the forces and virial. The developers usually need to implement an `AtomicModel` not a `Model`. +Subsequently, the `AtomicModel` is encapsulated using the `make_model(AtomicModel)` function, which leverages the `deepmd.pt.model.model.make_model.make_model` function. The purpose of the `make_model` wrapper is to facilitate the translation between atomic property predictions and the extended property predictions and differentiation , e.g. the reduction of atomic energy contribution and the autodiff for calculating the forces and virial. The developers usually need to implement an `AtomicModel` not a `Model`. ```py from deepmd.pt.model.atomic_model.base_atomic_model import ( diff --git a/doc/development/create-a-model-tf.md b/doc/development/create-a-model-tf.md index 7c4f5335ec..b39313a8d3 100644 --- a/doc/development/create-a-model-tf.md +++ b/doc/development/create-a-model-tf.md @@ -3,6 +3,7 @@ If you'd like to create a new model that isn't covered by the existing DeePMD-kit library, but reuse DeePMD-kit's other efficient modules such as data processing, trainner, etc, you may want to read this section. To incorporate your custom model you'll need to: + 1. Register and implement new components (e.g. descriptor) in a Python file. You may also want to register new TensorFlow OPs if necessary. 2. Register new arguments for user inputs. 3. Package new codes into a Python package. @@ -13,6 +14,7 @@ To incorporate your custom model you'll need to: When creating a new component, take descriptor as the example, one should inherit from the {py:class}`deepmd.tf.descriptor.descriptor.Descriptor` class and override several methods. Abstract methods such as {py:class}`deepmd.tf.descriptor.descriptor.Descriptor.build` must be implemented and others are not. You should keep arguments of these methods unchanged. After implementation, you need to register the component with a key: + ```py from deepmd.tf.descriptor import Descriptor diff --git a/doc/development/type-embedding.md b/doc/development/type-embedding.md index 5919d6c944..10eeed6ee9 100644 --- a/doc/development/type-embedding.md +++ b/doc/development/type-embedding.md @@ -1,11 +1,15 @@ # Atom Type Embedding + ## Overview + Here is an overview of the DeePMD-kit algorithm. Given a specific centric atom, we can obtain the matrix describing its local environment, named $\mathcal R$. It consists of the distance between the centric atom and its neighbors, as well as a direction vector. We can embed each distance into a vector of $M_1$ dimension by an `embedding net`, so the environment matrix $\mathcal R$ can be embedded into matrix $\mathcal G$. We can thus extract a descriptor vector (of $M_1 \times M_2$ dim) of the centric atom from the $\mathcal G$ by some matrix multiplication, and put the descriptor into `fitting net` to get the predicted energy $E$. The vanilla version of DeePMD-kit builds `embedding net` and `fitting net` relying on the atom type, resulting in $O(N)$ memory usage. After applying atom type embedding, in DeePMD-kit v2.0, we can share one `embedding net` and one `fitting net` in total, which reduces training complexity largely. ## Preliminary + In the following chart, you can find the meaning of symbols used to clarify the atom-type embedding algorithm. + $i$: Type of centric atom $j$: Type of neighbor atom @@ -40,8 +44,10 @@ $$E = F( [ \text{Multi}( \mathcal G( [s_{ij}, A(j)] ) ), A(j)] )$$ The difference between the two variants above is whether using the information of centric atom when generating the descriptor. Users can choose by modifying the `type_one_side` hyper-parameter in the input JSON file. ## How to use + A detailed introduction can be found at [`se_e2_a_tebd`](../model/train-se-e2-a-tebd.md). Looking for a fast start-up, you can simply add a `type_embedding` section in the input JSON file as displayed in the following, and the algorithm will adopt the atom type embedding algorithm automatically. An example of `type_embedding` is like + ```json "type_embedding":{ "neuron": [2, 4, 8], @@ -50,19 +56,26 @@ An example of `type_embedding` is like } ``` - ## Code Modification + Atom-type embedding can be applied to varied `embedding net` and `fitting net`, as a result, we build a class `TypeEmbedNet` to support this free combination. In the following, we will go through the execution process of the code to explain our code modification. ### trainer (train/trainer.py) + In trainer.py, it will parse the parameter from the input JSON file. If a `type_embedding` section is detected, it will build a `TypeEmbedNet`, which will be later input in the `model`. `model` will be built in the function `_build_network`. + ### model (model/ener.py) + When building the operation graph of the `model` in `model.build`. If a `TypeEmbedNet` is detected, it will build the operation graph of `type embed net`, `embedding net` and `fitting net` by order. The building process of `type embed net` can be found in `TypeEmbedNet.build`, which output the type embedding vector of each atom type (of [$\text{ntypes} \times \text{nchanl}$] dimensions). We then save the type embedding vector into `input_dict`, so that they can be fetched later in `embedding net` and `fitting net`. -### embedding net (descriptor/se*.py) + +### embedding net (descriptor/se\*.py) + In `embedding net`, we shall take local environment $\mathcal R$ as input and output matrix $\mathcal G$. Functions called in this process by the order is + ``` build -> _pass_filter -> _filter -> _filter_lower ``` + `_pass_filter`: It will first detect whether an atom type embedding exists, if so, it will apply atom type embedding algorithm and doesn't divide the input by type. `_filter`: It will call `_filter_lower` function to obtain the result of matrix multiplication ($\mathcal G^T\cdot \mathcal R$), do further multiplication involved in $\text{Multi}(\cdot)$, and finally output the result of descriptor vector of $M_1 \times M_2$ dim. @@ -70,8 +83,8 @@ build -> _pass_filter -> _filter -> _filter_lower `_filter_lower`: The main function handling input modification. If type embedding exists, it will call `_concat_type_embedding` function to concat the first column of input $\mathcal R$ (the column of $s_{ij}$) with the atom type embedding information. It will decide whether to use the atom type embedding vector of the centric atom according to the value of `type_one_side` (if set **True**, then we only use the vector of the neighbor atom). The modified input will be put into the `fitting net` to get $\mathcal G$ for further matrix multiplication stage. ### fitting net (fit/ener.py) -In `fitting net`, it takes the descriptor vector as input, whose dimension is [natoms, $M_1\times M_2$]. Because we need to involve information on the centric atom in this step, we need to generate a matrix named `atype_embed` (of dim [natoms, nchanl]), in which each row is the type embedding vector of the specific centric atom. The input is sorted by type of centric atom, we also know the number of a particular atom type (stored in `natoms[2+i]`), thus we get the type vector of the centric atom. In the build phase of the fitting net, it will check whether type embedding exists in `input_dict` and fetch them. After that, call `embed_atom_type` function to look up the embedding vector for the type vector of the centric atom to obtain `atype_embed`, and concat input with it ([input, atype_embed]). The modified input goes through `fitting` net` to get predicted energy. +In `fitting net`, it takes the descriptor vector as input, whose dimension is [natoms, $M_1\times M_2$]. Because we need to involve information on the centric atom in this step, we need to generate a matrix named `atype_embed` (of dim [natoms, nchanl]), in which each row is the type embedding vector of the specific centric atom. The input is sorted by type of centric atom, we also know the number of a particular atom type (stored in `natoms[2+i]`), thus we get the type vector of the centric atom. In the build phase of the fitting net, it will check whether type embedding exists in `input_dict` and fetch them. After that, call `embed_atom_type` function to look up the embedding vector for the type vector of the centric atom to obtain `atype_embed`, and concat input with it ([input, atype_embed]). The modified input goes through `fitting` net` to get predicted energy. :::{note} You can't apply the compression method while using atom-type embedding. diff --git a/doc/environment.yml b/doc/environment.yml index 635f24fe1e..85d5a97c5b 100644 --- a/doc/environment.yml +++ b/doc/environment.yml @@ -7,7 +7,7 @@ dependencies: - python=3.9 - pip>=20.1 - pip: - - ..[docs,cpu,torch] - - "exhale @ https://github.com/svenevs/exhale/archive/2759a394268307b88f5440487ae0920ee4ebf81e.zip" - # https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/309 - - docutils!=0.18.*,!=0.19.* + - ..[docs,cpu,torch] + - "exhale @ https://github.com/svenevs/exhale/archive/2759a394268307b88f5440487ae0920ee4ebf81e.zip" + # https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/309 + - docutils!=0.18.*,!=0.19.* diff --git a/doc/freeze/compress.md b/doc/freeze/compress.md index b6c8966c60..01cc9fa3a8 100644 --- a/doc/freeze/compress.md +++ b/doc/freeze/compress.md @@ -11,37 +11,46 @@ The compression of the DP model uses three techniques, tabulated inference, oper For better performance, the NN inference can be replaced by tabulated function evaluations if the input of the NN is of dimension one. The idea is to approximate the output of the NN by a piece-wise polynomial fitting. The input domain (a compact domain in $\mathbb R$) is divided into $L_c$ equally spaced intervals, in which we apply a fifth-order polynomial $g^l_m(x)$ approximation of the $m$-th output component of the NN function: + ```math g^l_m(x) = a^l_m x^5 + b^l_m x^4 + c^l_m x^3 + d^l_m x^2 + e^l_m x + f^l_m,\quad x \in [x_l, x_{l+1}), ``` + where $l=1,2,\dots,L_c$ is the index of the intervals, $x_1, \dots, x_{L_c}, x_{L_c+1}$ are the endpoints of the intervals, and $a^l_m$, $b^l_m$, $c^l_m$, $d^l_m$, $e^l_m$, and $f^l_m$ are the fitting parameters. The fitting parameters can be computed by the equations below: + ```math a^l_m = \frac{1}{2\Delta x_l^5}[12h_{m,l}-6(y'_{m,l+1}+y'_{m,l})\Delta x_l + (y''_{m,l+1}-y''_{m,l})\Delta x_l^2], ``` + ```math b^l_m = \frac{1}{2\Delta x_l^4}[-30h_{m,l} +(14y'_{m,l+1}+16y'_{m,l})\Delta x_l + (-2y''_{m,l+1}+3y''_{m,l})\Delta x_l^2], ``` + ```math c^l_m = \frac{1}{2\Delta x_l^3}[20h_{m,l}-(8y'_{m,l+1}+12y'_{m,l})\Delta x_l + (y''_{m,l+1}-3y''_{m,l})\Delta x_l^2], ``` + ```math d^l_m = \frac{1}{2}y''_{m,l}, ``` + ```math e^l_m = y_{m,l}', ``` + ```math f^l_m = y_{m,l}, ``` + where $\Delta x_l=x_{l+1}-x_l$ denotes the size of the interval. $h_{m,l}=y_{m,l+1}-y_{m,l}$. $y_{m,l} = y_m(x_l)$, $y'_{m,l} = y'_m(x_l)$ and $y''_{m,l} = y''_m(x_l)$ are the value, the first-order derivative, and the second-order derivative of the $m$-th component of the target NN function at the interval point $x_l$, respectively. The first and second-order derivatives are easily calculated by the back-propagation of the NN functions. -In the standard DP model inference, taking the [two-body embedding descriptor](../model/train-se-e2-a.md) as an example, the matrix product $(\mathcal G^i)^T \mathcal R$ requires the transfer of the tensor $\mathcal G^i$ between the register and the host/device memories, which usually becomes the bottle-neck of the computation due to the relatively small memory bandwidth of the GPUs. +In the standard DP model inference, taking the [two-body embedding descriptor](../model/train-se-e2-a.md) as an example, the matrix product $(\mathcal G^i)^T \mathcal R$ requires the transfer of the tensor $\mathcal G^i$ between the register and the host/device memories, which usually becomes the bottle-neck of the computation due to the relatively small memory bandwidth of the GPUs. The compressed DP model merges the matrix multiplication $(\mathcal G^i)^T \mathcal R$ with the tabulated inference step. More specifically, once one column of the $(\mathcal G^i)^T$ is evaluated, it is immediately multiplied with one row of the environment matrix in the register, and the outer product is deposited to the result of $(\mathcal G^i)^T \mathcal R$. -By the operator merging technique, the allocation of $\mathcal G^i$ and the memory movement between register and host/device memories is avoided. +By the operator merging technique, the allocation of $\mathcal G^i$ and the memory movement between register and host/device memories is avoided. The operator merging of the three-body embedding can be derived analogously. The first dimension, $N_c$, of the environment ($\mathcal R^i$) and embedding ($\mathcal G^i$) matrices is the expected maximum number of neighbors. @@ -49,19 +58,24 @@ If the number of neighbors of an atom is smaller than $N_c$, the corresponding p In practice, if the real number of neighbors is significantly smaller than $N_c$, a notable operation is spent on the multiplication of padding zeros. In the compressed DP model, the number of neighbors is precisely indexed at the tabulated inference stage, further saving computational costs.[^1] -[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). +[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). ## Instructions Once the frozen model is obtained from DeePMD-kit, we can get the neural network structure and its parameters (weights, biases, etc.) from the trained model, and compress it in the following way: + ```bash dp compress -i graph.pb -o graph-compress.pb ``` + where `-i` gives the original frozen model, `-o` gives the compressed model. Several other command line options can be passed to `dp compress`, which can be checked with + ```bash $ dp compress --help ``` + An explanation will be provided + ``` usage: dp compress [-h] [-v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [-l LOG_PATH] [-m {master,collect,workers}] [-i INPUT] [-o OUTPUT] @@ -118,11 +132,12 @@ optional arguments: The training script of the input frozen model (default: None) ``` + **Parameter explanation** Model compression, which includes tabulating the embedding net. -The table is composed of fifth-order polynomial coefficients and is assembled from two sub-tables. For model descriptor with `se_e2_a` type, the first sub-table takes the stride(parameter) as its uniform stride, while the second sub-table takes 10 * stride as its uniform stride; For model descriptor with `se_e3` type, the first sub-table takes 10 * stride as it's uniform stride, while the second sub-table takes 100 * stride as it's uniform stride. -The range of the first table is automatically detected by DeePMD-kit, while the second table ranges from the first table's upper boundary(upper) to the extrapolate(parameter) * upper. +The table is composed of fifth-order polynomial coefficients and is assembled from two sub-tables. For model descriptor with `se_e2_a` type, the first sub-table takes the stride(parameter) as its uniform stride, while the second sub-table takes 10 _ stride as its uniform stride; For model descriptor with `se_e3` type, the first sub-table takes 10 _ stride as it's uniform stride, while the second sub-table takes 100 _ stride as it's uniform stride. +The range of the first table is automatically detected by DeePMD-kit, while the second table ranges from the first table's upper boundary(upper) to the extrapolate(parameter) _ upper. Finally, we added a check frequency parameter. It indicates how often the program checks for overflow(if the input environment matrix overflows the first or second table range) during the MD inference. **Justification of model compression** @@ -131,14 +146,14 @@ Model compression, with little loss of accuracy, can greatly speed up MD inferen **Acceptable original model version** -The model compression interface requires the version of DeePMD-kit used in the original model generation should be `2.0.0-alpha.0` or above. If one has a frozen 1.2 or 1.3 model, one can upgrade it through the `dp convert-from` interface. (eg: ```dp convert-from 1.2/1.3 -i old_frozen_model.pb -o new_frozen_model.pb```) +The model compression interface requires the version of DeePMD-kit used in the original model generation should be `2.0.0-alpha.0` or above. If one has a frozen 1.2 or 1.3 model, one can upgrade it through the `dp convert-from` interface. (eg: `dp convert-from 1.2/1.3 -i old_frozen_model.pb -o new_frozen_model.pb`) **Acceptable descriptor type** Descriptors with `se_e2_a`, `se_e3`, `se_e2_r` and `se_atten_v2` types are supported by the model compression feature. `Hybrid` mixed with the above descriptors is also supported. - **Available activation functions for descriptor:** + - tanh - gelu - relu diff --git a/doc/freeze/freeze.md b/doc/freeze/freeze.md index 151c0b3b44..b80928a119 100644 --- a/doc/freeze/freeze.md +++ b/doc/freeze/freeze.md @@ -9,6 +9,7 @@ The trained neural network is extracted from a checkpoint and dumped into a prot ```bash $ dp freeze -o model.pb ``` + in the folder where the model is trained. The output model is called `model.pb`. ::: @@ -18,6 +19,7 @@ in the folder where the model is trained. The output model is called `model.pb`. ```bash $ dp --pt freeze -o model.pth ``` + in the folder where the model is trained. The output model is called `model.pth`. ::: @@ -25,8 +27,9 @@ in the folder where the model is trained. The output model is called `model.pth` :::: In [multi-task mode](../train/multi-task-training.md): + - This process will in default output several models, each of which contains the common descriptor and -one of the user-defined fitting nets in {ref}`fitting_net_dict `, let's name it `fitting_key`, together frozen in `graph_{fitting_key}.pb`. -Those frozen models are exactly the same as single-task output with fitting net `fitting_key`. + one of the user-defined fitting nets in {ref}`fitting_net_dict `, let's name it `fitting_key`, together frozen in `graph_{fitting_key}.pb`. + Those frozen models are exactly the same as single-task output with fitting net `fitting_key`. - If you add `--united-model` option in this situation, -the total multi-task model will be frozen into one unit `graph.pb`, which is mainly for multi-task initialization and can not be used directly for inference. + the total multi-task model will be frozen into one unit `graph.pb`, which is mainly for multi-task initialization and can not be used directly for inference. diff --git a/doc/inference/cxx.md b/doc/inference/cxx.md index cc7e7be540..58c74df068 100644 --- a/doc/inference/cxx.md +++ b/doc/inference/cxx.md @@ -1,6 +1,9 @@ # C/C++ interface + ## C++ interface + The C++ interface of DeePMD-kit is also available for the model interface, which is considered faster than the Python interface. An example `infer_water.cpp` is given below: + ```cpp #include "deepmd/DeepPot.h" @@ -14,14 +17,18 @@ int main(){ dp.compute (e, f, v, coord, atype, cell); } ``` + where `e`, `f` and `v` are predicted energy, force and virial of the system, respectively. See {cpp:class}`deepmd::DeepPot` for details. You can compile `infer_water.cpp` using `gcc`: + ```sh gcc infer_water.cpp -L $deepmd_root/lib -L $tensorflow_root/lib -I $deepmd_root/include -Wl,--no-as-needed -ldeepmd_cc -lstdc++ -ltensorflow_cc -Wl,-rpath=$deepmd_root/lib -Wl,-rpath=$tensorflow_root/lib -o infer_water ``` + and then run the program: + ```sh ./infer_water ``` @@ -31,6 +38,7 @@ and then run the program: Although C is harder to write, the C library will not be affected by different versions of C++ compilers. An example `infer_water.c` is given below: + ```cpp #include #include @@ -71,10 +79,13 @@ where `e`, `f` and `v` are predicted energy, force and virial of the system, res See {cpp:func}`DP_DeepPotCompute` for details. You can compile `infer_water.c` using `gcc`: + ```sh gcc infer_water.c -L $deepmd_root/lib -L $tensorflow_root/lib -I $deepmd_root/include -Wl,--no-as-needed -ldeepmd_c -Wl,-rpath=$deepmd_root/lib -Wl,-rpath=$tensorflow_root/lib -o infer_water ``` + and then run the program: + ```sh ./infer_water ``` @@ -103,10 +114,13 @@ Note that the feature of the header-only C++ library is still limited compared t See {cpp:class}`deepmd::hpp::DeepPot` for details. You can compile `infer_water_hpp.cpp` using `gcc`: + ```sh gcc infer_water_hpp.cpp -L $deepmd_root/lib -L $tensorflow_root/lib -I $deepmd_root/include -Wl,--no-as-needed -ldeepmd_c -Wl,-rpath=$deepmd_root/lib -Wl,-rpath=$tensorflow_root/lib -o infer_water_hpp ``` + and then run the program: + ```sh ./infer_water_hpp ``` diff --git a/doc/inference/nodejs.md b/doc/inference/nodejs.md index 72bfa6f9d9..8d58881898 100644 --- a/doc/inference/nodejs.md +++ b/doc/inference/nodejs.md @@ -9,9 +9,9 @@ const deepmd = require("deepmd-kit"); const dp = new deepmd.DeepPot("graph.pb"); -const coord = [1., 0., 0., 0., 0., 1.5, 1., 0., 3.]; +const coord = [1, 0, 0, 0, 0, 1.5, 1, 0, 3]; const atype = [1, 0, 1]; -const cell = [10., 0., 0., 0., 10., 0., 0., 0., 10.]; +const cell = [10, 0, 0, 0, 10, 0, 0, 0, 10]; const v_coord = new deepmd.vectord(coord.length); const v_atype = new deepmd.vectori(atype.length); @@ -20,15 +20,21 @@ for (var i = 0; i < coord.length; i++) v_coord.set(i, coord[i]); for (var i = 0; i < atype.length; i++) v_atype.set(i, atype[i]); for (var i = 0; i < cell.length; i++) v_cell.set(i, cell[i]); -var energy = 0.0 +var energy = 0.0; var v_forces = new deepmd.vectord(); var v_virials = new deepmd.vectord(); energy = dp.compute(energy, v_forces, v_virials, v_coord, v_atype, v_cell); console.log("energy:", energy); -console.log("forces:", [...Array(v_forces.size()).keys()].map(i => v_forces.get(i))); -console.log("virials:", [...Array(v_virials.size()).keys()].map(i => v_virials.get(i))); +console.log( + "forces:", + [...Array(v_forces.size()).keys()].map((i) => v_forces.get(i)), +); +console.log( + "virials:", + [...Array(v_virials.size()).keys()].map((i) => v_virials.get(i)), +); ``` Energy, forces, and virials will be printed to the screen. diff --git a/doc/inference/python.md b/doc/inference/python.md index db61cd7843..73faa2b329 100644 --- a/doc/inference/python.md +++ b/doc/inference/python.md @@ -1,6 +1,7 @@ # Python interface One may use the python interface of DeePMD-kit for model inference, an example is given as follows + ```python from deepmd.infer import DeepPot import numpy as np @@ -11,9 +12,11 @@ cell = np.diag(10 * np.ones(3)).reshape([1, -1]) atype = [1, 0, 1] e, f, v = dp.eval(coord, cell, atype) ``` + where `e`, `f` and `v` are predicted energy, force and virial of the system, respectively. Furthermore, one can use the python interface to calculate model deviation. + ```python from deepmd.infer import calc_model_devi from deepmd.infer import DeepPot as DP diff --git a/doc/install/build-conda.md b/doc/install/build-conda.md index fee9f77acc..14dee5c263 100644 --- a/doc/install/build-conda.md +++ b/doc/install/build-conda.md @@ -16,6 +16,7 @@ For example, if one wants to turn on `MPIIO` package in LAMMPS, go to [`lammps-f ``` This requires that Docker has been installed. After the building, the packages will be generated in `build_artifacts/linux-64` and `build_artifacts/noarch`, and then one can install then executing + ```sh conda create -n deepmd lammps -c file:///path/to/build_artifacts -c https://conda.deepmodeling.com -c nvidia ``` diff --git a/doc/install/easy-install.md b/doc/install/easy-install.md index 6acfd98cb0..0c56fdb0c5 100644 --- a/doc/install/easy-install.md +++ b/doc/install/easy-install.md @@ -18,21 +18,24 @@ Python 3.8 or above is required for Python interface. - [Install with docker](#install-with-docker) - [Install Python interface with pip](#install-python-interface-with-pip) - ## Install off-line packages + Both CPU and GPU version offline packages are available on [the Releases page](https://github.com/deepmodeling/deepmd-kit/releases). Some packages are split into two files due to the size limit of GitHub. One may merge them into one after downloading: + ```bash cat deepmd-kit-2.2.9-cuda118-Linux-x86_64.sh.0 deepmd-kit-2.2.9-cuda118-Linux-x86_64.sh.1 > deepmd-kit-2.2.9-cuda118-Linux-x86_64.sh ``` One may enable the environment using + ```bash conda activate /path/to/deepmd-kit ``` ## Install with conda + DeePMD-kit is available with [conda](https://github.com/conda/conda). Install [Anaconda](https://www.anaconda.com/distribution/#download-section), [Miniconda](https://docs.conda.io/en/latest/miniconda.html), or [miniforge](https://conda-forge.org/download/) first. You can refer to [DeepModeling conda FAQ](https://docs.deepmodeling.com/faq/conda.html) for how to setup a conda environment. @@ -58,35 +61,43 @@ Maintainers will build packages in the conda-forge organization together with ot :::: One may create an environment that contains the CPU version of DeePMD-kit and LAMMPS: + ```bash conda create -n deepmd deepmd-kit=*=*cpu libdeepmd=*=*cpu lammps -c https://conda.deepmodeling.com -c defaults ``` Or one may want to create a GPU environment containing [CUDA Toolkit](https://docs.nvidia.com/deploy/cuda-compatibility/index.html#binary-compatibility__table-toolkit-driver): + ```bash conda create -n deepmd deepmd-kit=*=*gpu libdeepmd=*=*gpu lammps cudatoolkit=11.6 horovod -c https://conda.deepmodeling.com -c defaults ``` + One could change the CUDA Toolkit version from `10.2` or `11.6`. One may specify the DeePMD-kit version such as `2.2.9` using + ```bash conda create -n deepmd deepmd-kit=2.2.9=*cpu libdeepmd=2.2.9=*cpu lammps horovod -c https://conda.deepmodeling.com -c defaults ``` One may enable the environment using + ```bash conda activate deepmd ``` ## Install with docker + A docker for installing the DeePMD-kit is available [here](https://github.com/deepmodeling/deepmd-kit/pkgs/container/deepmd-kit). To pull the CPU version: + ```bash docker pull ghcr.io/deepmodeling/deepmd-kit:2.2.8_cpu ``` To pull the GPU version: + ```bash docker pull ghcr.io/deepmodeling/deepmd-kit:2.2.8_cuda12.0_gpu ``` @@ -109,15 +120,18 @@ pip install deepmd-kit-cu11[gpu,cu11] ``` Or install the CPU version without CUDA supported: + ```bash pip install torch --index-url https://download.pytorch.org/whl/cpu pip install deepmd-kit[cpu] ``` [The LAMMPS module](../third-party/lammps-command.md) and [the i-Pi driver](../third-party/ipi.md) are only provided on Linux and macOS for the TensorFlow backend. To install LAMMPS and/or i-Pi, add `lmp` and/or `ipi` to extras: + ```bash pip install deepmd-kit[gpu,cu12,torch,lmp,ipi] ``` + MPICH is required for parallel running. (The macOS arm64 package doesn't support MPI yet.) It is suggested to install the package into an isolated environment. diff --git a/doc/install/install-from-source.md b/doc/install/install-from-source.md index 389cc78c9f..8676928e09 100644 --- a/doc/install/install-from-source.md +++ b/doc/install/install-from-source.md @@ -3,21 +3,26 @@ 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). Or get the DeePMD-kit source code by `git clone` + ```bash cd /some/workspace git clone https://github.com/deepmodeling/deepmd-kit.git deepmd-kit ``` For convenience, you may want to record the location of the source to a variable, saying `deepmd_source_dir` by + ```bash cd deepmd-kit deepmd_source_dir=`pwd` ``` ## Install the Python interface + ### Install Backend's Python interface + First, check the Python version on your machine. Python 3.8 or above is required. + ```bash python --version ``` @@ -36,16 +41,19 @@ pip install --upgrade pip :::{tab-item} TensorFlow {{ tensorflow_icon }} The full instruction to install TensorFlow can be found on the official [TensorFlow website](https://www.tensorflow.org/install/pip). TensorFlow 2.2 or later is supported. + ```bash pip install --upgrade tensorflow ``` If one does not need the GPU support of DeePMD-kit and is concerned about package size, the CPU-only version of TensorFlow should be installed by + ```bash pip install --upgrade tensorflow-cpu ``` To verify the installation, run + ```bash python -c "import tensorflow as tf;print(tf.reduce_sum(tf.random.normal([1000, 1000])))" ``` @@ -69,17 +77,23 @@ Follow [PyTorch documentation](https://pytorch.org/get-started/locally/) to inst :::: It is important that every time a new shell is started and one wants to use `DeePMD-kit`, the virtual environment should be activated by + ```bash source $deepmd_venv/bin/activate ``` + if one wants to skip out of the virtual environment, he/she can do + ```bash deactivate ``` + If one has multiple python interpreters named something like python3.x, it can be specified by, for example + ```bash virtualenv -p python3.8 $deepmd_venv ``` + One should remember to activate the virtual environment every time he/she uses DeePMD-kit. ### Install the DeePMD-kit's python interface @@ -103,6 +117,7 @@ Note that TensorFlow may have specific requirements for the compiler version to :::: Execute + ```bash cd $deepmd_source_dir pip install . @@ -110,26 +125,31 @@ pip install . One may set the following environment variables before executing `pip`: -| Environment variables | Allowed value | Default value | Usage | -| --------------------- | ---------------------- | ------------- | -------------------------- | -| DP_VARIANT | `cpu`, `cuda`, `rocm` | `cpu` | Build CPU variant or GPU variant with CUDA or ROCM support. | -| CUDAToolkit_ROOT | Path | Detected automatically | The path to the CUDA toolkit directory. CUDA 9.0 or later is supported. NVCC is required. | -| ROCM_ROOT | Path | Detected automatically | The path to the ROCM toolkit directory. | -| DP_ENABLE_TENSORFLOW | 0, 1 | 1 | {{ tensorflow_icon }} Enable the TensorFlow backend. -| TENSORFLOW_ROOT | Path | Detected automatically | {{ tensorflow_icon }} The path to TensorFlow Python library. By default the installer only finds TensorFlow under user site-package directory (`site.getusersitepackages()`) or system site-package directory (`sysconfig.get_path("purelib")`) due to limitation of [PEP-517](https://peps.python.org/pep-0517/). If not found, the latest TensorFlow (or the environment variable `TENSORFLOW_VERSION` if given) from PyPI will be built against.| -| DP_ENABLE_NATIVE_OPTIMIZATION | 0, 1 | 0 | Enable compilation optimization for the native machine's CPU type. Do not enable it if generated code will run on different CPUs. | -| CMAKE_ARGS | str | - | Additional CMake arguments | -| <LANG>FLAGS (``=`CXX`, `CUDA` or `HIP`) | str | - | Default compilation flags to be used when compiling `` files. See [CMake documentation](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html). | +| Environment variables | Allowed value | Default value | Usage | +| --------------------------------------------------- | --------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| DP_VARIANT | `cpu`, `cuda`, `rocm` | `cpu` | Build CPU variant or GPU variant with CUDA or ROCM support. | +| CUDAToolkit_ROOT | Path | Detected automatically | The path to the CUDA toolkit directory. CUDA 9.0 or later is supported. NVCC is required. | +| ROCM_ROOT | Path | Detected automatically | The path to the ROCM toolkit directory. | +| DP_ENABLE_TENSORFLOW | 0, 1 | 1 | {{ tensorflow_icon }} Enable the TensorFlow backend. | +| TENSORFLOW_ROOT | Path | Detected automatically | {{ tensorflow_icon }} The path to TensorFlow Python library. By default the installer only finds TensorFlow under user site-package directory (`site.getusersitepackages()`) or system site-package directory (`sysconfig.get_path("purelib")`) due to limitation of [PEP-517](https://peps.python.org/pep-0517/). If not found, the latest TensorFlow (or the environment variable `TENSORFLOW_VERSION` if given) from PyPI will be built against. | +| DP_ENABLE_NATIVE_OPTIMIZATION | 0, 1 | 0 | Enable compilation optimization for the native machine's CPU type. Do not enable it if generated code will run on different CPUs. | +| CMAKE_ARGS | str | - | Additional CMake arguments | +| <LANG>FLAGS (``=`CXX`, `CUDA` or `HIP`) | str | - | Default compilation flags to be used when compiling `` files. See [CMake documentation](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html). | To test the installation, one should first jump out of the source directory + ``` cd /some/other/workspace ``` + then execute + ```bash dp -h ``` + It will print the help information like + ```text usage: dp [-h] {train,freeze,test} ... @@ -149,12 +169,14 @@ Valid subcommands: ### Install horovod and mpi4py {{ tensorflow_icon }} [Horovod](https://github.com/horovod/horovod) and [mpi4py](https://github.com/mpi4py/mpi4py) are used for parallel training. For better performance on GPU, please follow the tuning steps in [Horovod on GPU](https://github.com/horovod/horovod/blob/master/docs/gpus.rst). + ```bash # With GPU, prefer NCCL as a communicator. HOROVOD_WITHOUT_GLOO=1 HOROVOD_WITH_TENSORFLOW=1 HOROVOD_GPU_OPERATIONS=NCCL HOROVOD_NCCL_HOME=/path/to/nccl pip install horovod mpi4py ``` If your work in a CPU environment, please prepare runtime as below: + ```bash # By default, MPI is used as communicator. HOROVOD_WITHOUT_GLOO=1 HOROVOD_WITH_TENSORFLOW=1 pip install horovod mpi4py @@ -218,6 +240,7 @@ You can also download libtorch prebuilt library from the [PyTorch website](https ### Install DeePMD-kit's C++ interface Now go to the source code directory of DeePMD-kit and make a building place. + ```bash cd $deepmd_source_dir/source mkdir build @@ -238,6 +261,7 @@ If you enable two or more backends, these backend libraries must be built in a c :::{tab-item} TensorFlow {{ tensorflow_icon }} I assume you have activated the TensorFlow Python environment and want to install DeePMD-kit into path `$deepmd_root`, then execute CMake + ```bash cmake -DENABLE_TENSORFLOW=TRUE -DUSE_TF_PYTHON_LIBS=TRUE -DCMAKE_INSTALL_PREFIX=$deepmd_root .. ``` @@ -249,38 +273,43 @@ If you specify `-DUSE_TF_PYTHON_LIBS=FALSE`, you need to give the location where :::{tab-item} PyTorch {{ pytorch_icon }} I assume you have installed the PyTorch (either Python or C++ interface) to `$torch_root`, then execute CMake + ```bash cmake -DENABLE_PYTORCH=TRUE -DCMAKE_PREFIX_PATH=$torch_root -DCMAKE_INSTALL_PREFIX=$deepmd_root .. ``` + ::: :::: One may add the following arguments to `cmake`: -| CMake Aurgements | Allowed value | Default value | Usage | -| ------------------------ | ------------------- | ------------- | ------------------------| -| -DENABLE_TENSORFLOW=<value> | `TRUE` or `FALSE` | `FALSE` | {{ tensorflow_icon }} Whether building the TensorFlow backend. | -| -DENABLE_PYTORCH=<value> | `TRUE` or `FALSE` | `FALSE` | {{ pytorch_icon }} Whether building the PyTorch backend. | -| -DTENSORFLOW_ROOT=<value> | Path | - | {{ tensorflow_icon }} The Path to TensorFlow's C++ interface. | -| -DCMAKE_INSTALL_PREFIX=<value> | Path | - | The Path where DeePMD-kit will be installed. | -| -DUSE_CUDA_TOOLKIT=<value> | `TRUE` or `FALSE` | `FALSE` | If `TRUE`, Build GPU support with CUDA toolkit. | -| -DCUDAToolkit_ROOT=<value> | Path | Detected automatically | The path to the CUDA toolkit directory. CUDA 9.0 or later is supported. NVCC is required. | -| -DUSE_ROCM_TOOLKIT=<value> | `TRUE` or `FALSE` | `FALSE` | If `TRUE`, Build GPU support with ROCM toolkit. | -| -DCMAKE_HIP_COMPILER_ROCM_ROOT=<value> | Path | Detected automatically | The path to the ROCM toolkit directory. | -| -DLAMMPS_SOURCE_ROOT=<value> | Path | - | Only neccessary for LAMMPS plugin mode. The path to the [LAMMPS source code](install-lammps.md). LAMMPS 8Apr2021 or later is supported. If not assigned, the plugin mode will not be enabled. | -| -DUSE_TF_PYTHON_LIBS=<value> | `TRUE` or `FALSE` | `FALSE` | {{ tensorflow_icon }} If `TRUE`, Build C++ interface with TensorFlow's Python libraries (TensorFlow's Python Interface is required). And there's no need for building TensorFlow's C++ interface.| -| -DENABLE_NATIVE_OPTIMIZATION=<value> | `TRUE` or `FALSE` | `FALSE` | Enable compilation optimization for the native machine's CPU type. Do not enable it if generated code will run on different CPUs. | -| -DCMAKE_<LANG>_FLAGS=<value> (``=`CXX`, `CUDA` or `HIP`) | str | - | Default compilation flags to be used when compiling `` files. See [CMake documentation](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html). | +| CMake Aurgements | Allowed value | Default value | Usage | +| ---------------------------------------------------------------------------- | ----------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| -DENABLE_TENSORFLOW=<value> | `TRUE` or `FALSE` | `FALSE` | {{ tensorflow_icon }} Whether building the TensorFlow backend. | +| -DENABLE_PYTORCH=<value> | `TRUE` or `FALSE` | `FALSE` | {{ pytorch_icon }} Whether building the PyTorch backend. | +| -DTENSORFLOW_ROOT=<value> | Path | - | {{ tensorflow_icon }} The Path to TensorFlow's C++ interface. | +| -DCMAKE_INSTALL_PREFIX=<value> | Path | - | The Path where DeePMD-kit will be installed. | +| -DUSE_CUDA_TOOLKIT=<value> | `TRUE` or `FALSE` | `FALSE` | If `TRUE`, Build GPU support with CUDA toolkit. | +| -DCUDAToolkit_ROOT=<value> | Path | Detected automatically | The path to the CUDA toolkit directory. CUDA 9.0 or later is supported. NVCC is required. | +| -DUSE_ROCM_TOOLKIT=<value> | `TRUE` or `FALSE` | `FALSE` | If `TRUE`, Build GPU support with ROCM toolkit. | +| -DCMAKE_HIP_COMPILER_ROCM_ROOT=<value> | Path | Detected automatically | The path to the ROCM toolkit directory. | +| -DLAMMPS_SOURCE_ROOT=<value> | Path | - | Only neccessary for LAMMPS plugin mode. The path to the [LAMMPS source code](install-lammps.md). LAMMPS 8Apr2021 or later is supported. If not assigned, the plugin mode will not be enabled. | +| -DUSE_TF_PYTHON_LIBS=<value> | `TRUE` or `FALSE` | `FALSE` | {{ tensorflow_icon }} If `TRUE`, Build C++ interface with TensorFlow's Python libraries (TensorFlow's Python Interface is required). And there's no need for building TensorFlow's C++ interface. | +| -DENABLE_NATIVE_OPTIMIZATION=<value> | `TRUE` or `FALSE` | `FALSE` | Enable compilation optimization for the native machine's CPU type. Do not enable it if generated code will run on different CPUs. | +| -DCMAKE\_<LANG>\_FLAGS=<value> (``=`CXX`, `CUDA` or `HIP`) | str | - | Default compilation flags to be used when compiling `` files. See [CMake documentation](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html). | If the CMake has been executed successfully, then run the following make commands to build the package: + ```bash make -j4 make install ``` + Option `-j4` means using 4 processes in parallel. You may want to use a different number according to your hardware. If everything works fine, you will have the executable and libraries installed in `$deepmd_root/bin` and `$deepmd_root/lib` + ```bash $ ls $deepmd_root/bin $ ls $deepmd_root/lib diff --git a/doc/install/install-gromacs.md b/doc/install/install-gromacs.md index 758ad7784a..147822cf17 100644 --- a/doc/install/install-gromacs.md +++ b/doc/install/install-gromacs.md @@ -3,11 +3,14 @@ Before following this section, [DeePMD-kit C++ interface](install-from-source.md) should have be installed. ## Patch source code of GROMACS + Download the source code of a supported GROMACS version (2020.2) from https://manual.gromacs.org/2020.2/download.html. Run the following command: + ```bash export PATH=$PATH:$deepmd_kit_root/bin dp_gmx_patch -d $gromacs_root -v $version -p ``` + where `deepmd_kit_root` is the directory where the latest version of DeePMD-kit is installed, and `gromacs_root` refers to the source code directory of GROMACS. And `version` represents the version of GROMACS, where **only 2020.2 is supported now**. If attempting to patch another version of GROMACS you will still need to set `version` to `2020.2` as this is the only supported version, we cannot guarantee that patching other versions of GROMACS will work. ## Compile GROMACS with deepmd-kit + The C++ interface of `Deepmd-kit 2.x` and `TensorFlow 2.x` are required. And be aware that only DeePMD-kit with **high precision** is supported now since we cannot ensure single precision is enough for a GROMACS simulation. Here is a sample compile script: + ```bash #!/bin/bash export CC=/usr/bin/gcc diff --git a/doc/install/install-ipi.md b/doc/install/install-ipi.md index 1f4de7474c..3dd45d6749 100644 --- a/doc/install/install-ipi.md +++ b/doc/install/install-ipi.md @@ -1,11 +1,14 @@ # Install i-PI + The i-PI works in a client-server model. The i-PI provides the server for integrating the replica positions of atoms, while the DeePMD-kit provides a client named `dp_ipi` that computes the interactions (including energy, forces and virials). The server and client communicate via the Unix domain socket or the Internet socket. Full documentation for i-PI can be found [here](http://ipi-code.org/). The source code and a complete installation guide for i-PI can be found [here](https://github.com/i-pi/i-pi). To use i-PI with already existing drivers, install and update using Pip: + ```bash pip install -U i-PI ``` Test with Pytest: + ```bash pip install pytest pytest --pyargs ipi.tests diff --git a/doc/install/install-lammps.md b/doc/install/install-lammps.md index 21e1e72dd1..c24bfac06b 100644 --- a/doc/install/install-lammps.md +++ b/doc/install/install-lammps.md @@ -3,6 +3,7 @@ There are two ways to install LAMMPS: the built-in mode and the plugin mode. The built-in mode builds LAMMPS along with the DeePMD-kit and DeePMD-kit will be loaded automatically when running LAMMPS. The plugin mode builds LAMMPS and a plugin separately, so one needs to use `plugin load` command to load the DeePMD-kit's LAMMPS plugin library. ## Install LAMMPS's DeePMD-kit module (built-in mode) + Before following this section, [DeePMD-kit C++ interface](install-from-source.md) should have be installed. DeePMD-kit provides a module for running MD simulations with LAMMPS. Now make the DeePMD-kit module for LAMMPS. @@ -11,12 +12,15 @@ DeePMD-kit provides a module for running MD simulations with LAMMPS. Now make th cd $deepmd_source_dir/source/build make lammps ``` + DeePMD-kit will generate a module called `USER-DEEPMD` in the `build` directory, which supports either double or single float precision interface. Now download the LAMMPS code, and uncompress it. + ```bash cd /some/workspace wget https://github.com/lammps/lammps/archive/stable_2Aug2023_update3.tar.gz tar xf stable_2Aug2023_update3.tar.gz ``` + The source code of LAMMPS is stored in the directory `lammps-stable_2Aug2023_update3`. Then, you can [build LAMMPS](https://docs.lammps.org/Build.html) with either make or CMake. @@ -24,6 +28,7 @@ Then, you can [build LAMMPS](https://docs.lammps.org/Build.html) with either mak ### With make Now go into the LAMMPS code and copy the DeePMD-kit module like this + ```bash cd lammps-stable_2Aug2023_update3/src/ cp -r $deepmd_source_dir/source/build/USER-DEEPMD . @@ -31,17 +36,21 @@ make yes-kspace make yes-extra-fix make yes-user-deepmd ``` + You can enable any other package you want. Now build LAMMPS + ```bash make mpi -j4 ``` If everything works fine, you will end up with an executable `lmp_mpi`. + ```bash ./lmp_mpi -h ``` The DeePMD-kit module can be removed from the LAMMPS source code by + ```bash make no-user-deepmd ``` @@ -64,6 +73,7 @@ echo "include(${deepmd_source_dir}/source/lmp/builtin.cmake)" >> ../cmake/CMakeL It's expected to see one extra line in the end of `CMakeLists.txt`. Now build LAMMPS. You can install any other package you want. + ```bash cmake -D LAMMPS_INSTALL_RPATH=ON -D BUILD_SHARED_LIBS=yes -D CMAKE_INSTALL_PREFIX=${deepmd_root} -DCMAKE_PREFIX_PATH=${deepmd_root} ../cmake make -j4 @@ -71,14 +81,17 @@ make install ``` If everything works fine, you will end up with an executable `${deepmd_root}/bin/lmp`. + ```bash ${deepmd_root}/bin/lmp -h ``` ## Install LAMMPS (plugin mode) + Starting from `8Apr2021`, LAMMPS also provides a plugin mode, allowing one to build LAMMPS and a plugin separately. Now download the LAMMPS code (`8Apr2021` or later), and uncompress it: + ```bash cd /some/workspace wget https://github.com/lammps/lammps/archive/stable_2Aug2023_update3.tar.gz @@ -91,7 +104,9 @@ The source code of LAMMPS is stored in the directory `lammps-stable_2Aug2023_upd mkdir -p lammps-stable_2Aug2023_update3/build/ cd lammps-stable_2Aug2023_update3/build/ ``` + Now build LAMMPS. Note that `PLUGIN` must be enabled, and `BUILD_SHARED_LIBS` must be set to `yes`. You can install any other package you want. + ```bash cmake -D PKG_PLUGIN=ON -D LAMMPS_INSTALL_RPATH=ON -D BUILD_SHARED_LIBS=yes -D CMAKE_INSTALL_PREFIX=${deepmd_root} -D CMAKE_INSTALL_LIBDIR=lib -D CMAKE_INSTALL_FULL_LIBDIR=${deepmd_root}/lib ../cmake make -j4 @@ -99,6 +114,7 @@ make install ``` If everything works fine, you will end up with an executable `${deepmd_root}/bin/lmp`. + ```bash ${deepmd_root}/bin/lmp -h ``` @@ -109,4 +125,5 @@ If `${tensorflow_root}`, `${deepmd_root}`, or the path to TensorFlow Python pack ```sh patchelf --add-rpath "${tensorflow_root}/lib" liblammps.so ``` + ::: diff --git a/doc/install/install-tf.1.12.md b/doc/install/install-tf.1.12.md index f4009405d7..13abd8f7a7 100644 --- a/doc/install/install-tf.1.12.md +++ b/doc/install/install-tf.1.12.md @@ -1,5 +1,7 @@ # Install TensorFlow's C++ interface + The TensorFlow's C++ interface will be compiled from the source code. Firstly one installs bazel. It is highly recommended that the bazel version 0.15.0 is used. A full instruction of bazel installation can be found [here](https://docs.bazel.build/versions/master/install.html). + ```bash cd /some/workspace wget https://github.com/bazelbuild/bazel/releases/download/0.15.0/bazel-0.15.0-dist.zip @@ -11,6 +13,7 @@ export PATH=`pwd`/output:$PATH ``` Firstly get the source code of the TensorFlow + ```bash cd /some/workspace git clone https://github.com/tensorflow/tensorflow tensorflow -b v1.12.0 --depth=1 @@ -18,26 +21,35 @@ cd tensorflow ``` DeePMD-kit is compiled by CMake, so we need to compile and integrate TensorFlow with CMake projects. The rest of this section follows [the instruction provided by Tuatini](http://tuatini.me/building-tensorflow-as-a-standalone-project/). Now execute + ```bash ./configure ``` + You will answer a list of questions that help configure the building of TensorFlow. It is recommended to build for Python3. You may want to answer the question like this (please replace `$tensorflow_venv` with the virtual environment directory): + ```bash Please specify the location of python. [Default is $tensorflow_venv/bin/python]: ``` + The library path for Python should be set accordingly. Now build the shared library of TensorFlow: + ```bash bazel build -c opt --verbose_failures //tensorflow:libtensorflow_cc.so ``` -You may want to add options `--copt=-msse4.2`, `--copt=-mavx`, `--copt=-mavx2` and `--copt=-mfma` to enable SSE4.2, AVX, AVX2 and FMA SIMD accelerations, respectively. It is noted that these options should be chosen according to the CPU architecture. If the RAM becomes an issue for your machine, you may limit the RAM usage by using `--local_resources 2048,.5,1.0`. + +You may want to add options `--copt=-msse4.2`, `--copt=-mavx`, `--copt=-mavx2` and `--copt=-mfma` to enable SSE4.2, AVX, AVX2 and FMA SIMD accelerations, respectively. It is noted that these options should be chosen according to the CPU architecture. If the RAM becomes an issue for your machine, you may limit the RAM usage by using `--local_resources 2048,.5,1.0`. Now I assume you want to install TensorFlow in directory `$tensorflow_root`. Create the directory if it does not exist + ```bash mkdir -p $tensorflow_root ``` + Before moving on, we need to compile the dependencies of TensorFlow, including Protobuf, Eigen, nsync and absl. Firstly, protobuf + ```bash mkdir /tmp/proto sed -i 's;PROTOBUF_URL=.*;PROTOBUF_URL=\"https://mirror.bazel.build/github.com/google/protobuf/archive/v3.6.0.tar.gz\";g' tensorflow/contrib/makefile/download_dependencies.sh @@ -48,7 +60,9 @@ cd tensorflow/contrib/makefile/downloads/protobuf/ make make install ``` + Then Eigen + ```bash mkdir /tmp/eigen cd ../eigen @@ -57,7 +71,9 @@ cd build_dir cmake -DCMAKE_INSTALL_PREFIX=/tmp/eigen/ ../ make install ``` + nsync + ```bash mkdir /tmp/nsync cd ../../nsync @@ -67,7 +83,9 @@ cmake -DCMAKE_INSTALL_PREFIX=/tmp/nsync/ ../ make make install ``` + And absl + ```bash cd ../../absl bazel build @@ -75,7 +93,9 @@ mkdir -p $tensorflow_root/include/ rsync -avzh --include '*/' --include '*.h' --exclude '*' absl $tensorflow_root/include/ cd ../../../../.. ``` + Now, copy the libraries to the tensorflow's installation directory: + ```bash mkdir $tensorflow_root/lib cp bazel-bin/tensorflow/libtensorflow_cc.so $tensorflow_root/lib/ @@ -83,7 +103,9 @@ cp bazel-bin/tensorflow/libtensorflow_framework.so $tensorflow_root/lib/ cp /tmp/proto/lib/libprotobuf.a $tensorflow_root/lib/ cp /tmp/nsync/lib64/libnsync.a $tensorflow_root/lib/ ``` + Then copy the headers + ```bash mkdir -p $tensorflow_root/include/tensorflow cp -r bazel-genfiles/* $tensorflow_root/include/ @@ -94,12 +116,16 @@ cp -r /tmp/proto/include/* $tensorflow_root/include cp -r /tmp/eigen/include/eigen3/* $tensorflow_root/include cp -r /tmp/nsync/include/*h $tensorflow_root/include ``` + Now clean up the source files in the header directories: + ```bash cd $tensorflow_root/include find . -name "*.cc" -type f -delete ``` + The temporary installation directories for the dependencies can be removed: + ```bash rm -fr /tmp/proto /tmp/eigen /tmp/nsync ``` diff --git a/doc/install/install-tf.1.14-gpu.md b/doc/install/install-tf.1.14-gpu.md index 4e9fcaf7fc..5850af24ba 100644 --- a/doc/install/install-tf.1.14-gpu.md +++ b/doc/install/install-tf.1.14-gpu.md @@ -1,5 +1,7 @@ # Install TensorFlow-GPU's C++ interface + TensorFlow's C++ interface will be compiled from the source code. Firstly one installs Bazel. It is highly recommended that the Bazel version 0.24.1 is used. Full instructions on Bazel installation can be found [here](https://docs.bazel.build/versions/master/install.html). + ```bash cd /some/workspace wget https://github.com/bazelbuild/bazel/releases/download/0.24.1/bazel-0.24.1-dist.zip @@ -11,6 +13,7 @@ export PATH=`pwd`/output:$PATH ``` Firstly get the source code of the TensorFlow + ```bash cd /some/workspace git clone https://github.com/tensorflow/tensorflow tensorflow -b v1.14.0 --depth=1 @@ -20,6 +23,7 @@ cd tensorflow DeePMD-kit is compiled by CMake, so we need to compile and integrate TensorFlow with CMake projects. The rest of this section follows [the instruction provided by Tuatini](http://tuatini.me/building-tensorflow-as-a-standalone-project/). Now execute You will answer a list of questions that help configure the building of TensorFlow. It is recommended to build for Python3. You may want to answer the question like this (please replace `$tensorflow_venv` with the virtual environment directory): + ```bash ./configure Please specify the location of python. [Default is xxx]: @@ -93,23 +97,30 @@ Configuration finished The library path for Python should be set accordingly. Now build the shared library of TensorFlow: + ```bash bazel build -c opt --verbose_failures //tensorflow:libtensorflow_cc.so ``` -You may want to add options `--copt=-msse4.2`, `--copt=-mavx`, `--copt=-mavx2` and `--copt=-mfma` to enable SSE4.2, AVX, AVX2 and FMA SIMD accelerations, respectively. It is noted that these options should be chosen according to the CPU architecture. If the RAM becomes an issue for your machine, you may limit the RAM usage by using `--local_resources 2048,.5,1.0`. + +You may want to add options `--copt=-msse4.2`, `--copt=-mavx`, `--copt=-mavx2` and `--copt=-mfma` to enable SSE4.2, AVX, AVX2 and FMA SIMD accelerations, respectively. It is noted that these options should be chosen according to the CPU architecture. If the RAM becomes an issue for your machine, you may limit the RAM usage by using `--local_resources 2048,.5,1.0`. Now I assume you want to install TensorFlow in directory `$tensorflow_root`. Create the directory if it does not exist + ```bash mkdir -p $tensorflow_root ``` + Now, copy the libraries to the TensorFlow's installation directory: + ```bash mkdir $tensorflow_root/lib cp -d bazel-bin/tensorflow/libtensorflow_cc.so* $tensorflow_root/lib/ cp -d bazel-bin/tensorflow/libtensorflow_framework.so* $tensorflow_root/lib/ cp -d $tensorflow_root/lib/libtensorflow_framework.so.1 $tensorflow_root/lib/libtensorflow_framework.so ``` + Then copy the headers + ```bash mkdir -p $tensorflow_root/include/tensorflow cp -r bazel-genfiles/* $tensorflow_root/include/ @@ -121,16 +132,20 @@ cp -r bazel-tensorflow/external/eigen_archive/unsupported/ $tensorflow_root/incl rsync -avzh --include '*/' --include '*.h' --include '*.inc' --exclude '*' bazel-tensorflow/external/protobuf_archive/src/ $tensorflow_root/include/ rsync -avzh --include '*/' --include '*.h' --include '*.inc' --exclude '*' bazel-tensorflow/external/com_google_absl/absl/ $tensorflow_root/include/absl ``` + Now clean up the source files in the header directories: + ```bash cd $tensorflow_root/include find . -name "*.cc" -type f -delete ``` # Troubleshooting + ```bash git: unknown command -C ... ``` + This may be your git version issue because the low version of Git does not support this command. Upgrading your Git may be helpful. ```bash @@ -139,9 +154,11 @@ Please set them or make sure they are set and tested correctly in the CMake file FFTW_LIB (ADVANCED) linked by target "FFTW" in directory xxx ``` + Currently, when building the Eigen package, you can delete the FFTW in the CMake file. ```bash fatal error: absl/numeric/int128_have_intrinsic.inc: No such file or directory ``` + Basically, you could build an empty file named "int128_have_intrinsic.inc" in the same directory of "int128.h". diff --git a/doc/install/install-tf.1.14.md b/doc/install/install-tf.1.14.md index 065df9cad9..6457d484ad 100644 --- a/doc/install/install-tf.1.14.md +++ b/doc/install/install-tf.1.14.md @@ -1,5 +1,7 @@ # Install tensorflow's C++ interface + The tensorflow's C++ interface will be compiled from the source code. Firstly one installs bazel. It is highly recommended that the bazel version 0.24.1 is used. A full instruction of bazel installation can be found [here](https://docs.bazel.build/versions/master/install.html). + ```bash cd /some/workspace wget https://github.com/bazelbuild/bazel/releases/download/0.24.1/bazel-0.24.1-dist.zip @@ -11,6 +13,7 @@ export PATH=`pwd`/output:$PATH ``` Firstly get the source code of the tensorflow + ```bash cd /some/workspace git clone https://github.com/tensorflow/tensorflow tensorflow -b v1.14.0 --depth=1 @@ -18,33 +21,44 @@ cd tensorflow ``` DeePMD-kit is compiled by cmake, so we need to compile and integrate tensorflow with cmake projects. The rest of this section basically follows [the instruction provided by Tuatini](http://tuatini.me/building-tensorflow-as-a-standalone-project/). Now execute + ```bash ./configure ``` + You will answer a list of questions that help configure the building of tensorflow. It is recommended to build for Python3. You may want to answer the question like this (please replace `$tensorflow_venv` by the virtual environment directory): + ```bash Please specify the location of python. [Default is $tensorflow_venv/bin/python]: ``` + The library path for Python should be set accordingly. Now build the shared library of tensorflow: + ```bash bazel build -c opt --verbose_failures //tensorflow:libtensorflow_cc.so ``` -You may want to add options `--copt=-msse4.2`, `--copt=-mavx`, `--copt=-mavx2` and `--copt=-mfma` to enable SSE4.2, AVX, AVX2 and FMA SIMD accelerations, respectively. It is noted that these options should be chosen according to the CPU architecture. If the RAM becomes an issue of your machine, you may limit the RAM usage by using `--local_resources 2048,.5,1.0`. + +You may want to add options `--copt=-msse4.2`, `--copt=-mavx`, `--copt=-mavx2` and `--copt=-mfma` to enable SSE4.2, AVX, AVX2 and FMA SIMD accelerations, respectively. It is noted that these options should be chosen according to the CPU architecture. If the RAM becomes an issue of your machine, you may limit the RAM usage by using `--local_resources 2048,.5,1.0`. Now I assume you want to install tensorflow in directory `$tensorflow_root`. Create the directory if it does not exists + ```bash mkdir -p $tensorflow_root ``` + Now, copy the libraries to the tensorflow's installation directory: + ```bash mkdir $tensorflow_root/lib cp -d bazel-bin/tensorflow/libtensorflow_cc.so* $tensorflow_root/lib/ cp -d bazel-bin/tensorflow/libtensorflow_framework.so* $tensorflow_root/lib/ cp -d $tensorflow_root/lib/libtensorflow_framework.so.1 $tensorflow_root/lib/libtensorflow_framework.so ``` + Then copy the headers + ```bash mkdir -p $tensorflow_root/include/tensorflow cp -r bazel-genfiles/* $tensorflow_root/include/ @@ -56,7 +70,9 @@ cp -r bazel-tensorflow/external/eigen_archive/unsupported/ $tensorflow_root/incl rsync -avzh --include '*/' --include '*.h' --include '*.inc' --exclude '*' bazel-tensorflow/external/protobuf_archive/src/ $tensorflow_root/include/ rsync -avzh --include '*/' --include '*.h' --include '*.inc' --exclude '*' bazel-tensorflow/external/com_google_absl/absl/ $tensorflow_root/include/absl ``` + Now clean up the source files in the header directories: + ```bash cd $tensorflow_root/include find . -name "*.cc" -type f -delete diff --git a/doc/install/install-tf.1.8.md b/doc/install/install-tf.1.8.md index bfc1a616d4..f9554f9348 100644 --- a/doc/install/install-tf.1.8.md +++ b/doc/install/install-tf.1.8.md @@ -1,5 +1,7 @@ # Install tensorflow's C++ interface + The tensorflow's C++ interface will be compiled from the source code. Firstly one installs bazel. It is highly recommended that the bazel version 0.10.0 is used. A full instruction of bazel installation can be found [here](https://docs.bazel.build/versions/master/install.html). + ```bash cd /some/workspace wget https://github.com/bazelbuild/bazel/releases/download/0.10.0/bazel-0.10.0-dist.zip @@ -11,6 +13,7 @@ export PATH=`pwd`/output:$PATH ``` Firstly get the source code of the TensorFlow + ```bash cd /some/workspace git clone https://github.com/tensorflow/tensorflow tensorflow -b v1.8.0 --depth=1 @@ -18,26 +21,35 @@ cd tensorflow ``` DeePMD-kit is compiled by CMake, so we need to compile and integrate TensorFlow with CMake projects. The rest of this section basically follows [the instruction provided by Tuatini](http://tuatini.me/building-tensorflow-as-a-standalone-project/). Now execute + ```bash ./configure ``` + You will answer a list of questions that help configure the building of TensorFlow. It is recommended to build for Python3. You may want to answer the question like this (please replace `$tensorflow_venv` with the virtual environment directory): + ```bash Please specify the location of python. [Default is $tensorflow_venv/bin/python]: ``` + The library path for Python should be set accordingly. Now build the shared library of TensorFlow: + ```bash bazel build -c opt --verbose_failures //tensorflow:libtensorflow_cc.so ``` -You may want to add options `--copt=-msse4.2`, `--copt=-mavx`, `--copt=-mavx2` and `--copt=-mfma` to enable SSE4.2, AVX, AVX2 and FMA SIMD accelerations, respectively. It is noted that these options should be chosen according to the CPU architecture. If the RAM becomes an issue of your machine, you may limit the RAM usage by using `--local_resources 2048,.5,1.0`. + +You may want to add options `--copt=-msse4.2`, `--copt=-mavx`, `--copt=-mavx2` and `--copt=-mfma` to enable SSE4.2, AVX, AVX2 and FMA SIMD accelerations, respectively. It is noted that these options should be chosen according to the CPU architecture. If the RAM becomes an issue of your machine, you may limit the RAM usage by using `--local_resources 2048,.5,1.0`. Now I assume you want to install TensorFlow in directory `$tensorflow_root`. Create the directory if it does not exist + ```bash mkdir -p $tensorflow_root ``` + Before moving on, we need to compile the dependencies of TensorFlow, including Protobuf, Eigen and nsync. Firstly, protobuf + ```bash mkdir /tmp/proto tensorflow/contrib/makefile/download_dependencies.sh @@ -47,7 +59,9 @@ cd tensorflow/contrib/makefile/downloads/protobuf/ make make install ``` + Then Eigen + ```bash mkdir /tmp/eigen cd ../eigen @@ -56,7 +70,9 @@ cd build_dir cmake -DCMAKE_INSTALL_PREFIX=/tmp/eigen/ ../ make install ``` + And nsync + ```bash mkdir /tmp/nsync cd ../../nsync @@ -67,7 +83,9 @@ make make install cd ../../../../../.. ``` + Now, copy the libraries to the TensorFlow's installation directory: + ```bash mkdir $tensorflow_root/lib cp bazel-bin/tensorflow/libtensorflow_cc.so $tensorflow_root/lib/ @@ -75,7 +93,9 @@ cp bazel-bin/tensorflow/libtensorflow_framework.so $tensorflow_root/lib/ cp /tmp/proto/lib/libprotobuf.a $tensorflow_root/lib/ cp /tmp/nsync/lib/libnsync.a $tensorflow_root/lib/ ``` + Then copy the headers + ```bash mkdir -p $tensorflow_root/include/tensorflow cp -r bazel-genfiles/* $tensorflow_root/include/ @@ -86,12 +106,16 @@ cp -r /tmp/proto/include/* $tensorflow_root/include cp -r /tmp/eigen/include/eigen3/* $tensorflow_root/include cp -r /tmp/nsync/include/*h $tensorflow_root/include ``` + Now clean up the source files in the header directories: + ```bash cd $tensorflow_root/include find . -name "*.cc" -type f -delete ``` + The temporary installation directories for the dependencies can be removed: + ```bash rm -fr /tmp/proto /tmp/eigen /tmp/nsync ``` diff --git a/doc/install/install-tf.2.12.md b/doc/install/install-tf.2.12.md index dce0c224d5..8523345d3d 100644 --- a/doc/install/install-tf.2.12.md +++ b/doc/install/install-tf.2.12.md @@ -1,4 +1,5 @@ # Install TensorFlow's C++ interface + TensorFlow's C++ interface will be compiled from the source code. In this manual, we install TensorFlow 2.12.0. It is noted that the source code of TensorFlow 2.12.0 uses C++ 17, so one needs a C++ compiler that supports C++ 17. Firstly one installs Bazel. [bazelisk](https://github.com/bazelbuild/bazelisk) can be lanuched to use [bazel](https://github.com/bazelbuild/bazel). @@ -10,6 +11,7 @@ export PATH=/some/workspace/bazel/bin:$PATH ``` Firstly get the source code of the TensorFlow + ```bash git clone https://github.com/tensorflow/tensorflow tensorflow -b v2.12.0 --depth=1 cd tensorflow @@ -76,23 +78,30 @@ Configuration finished The library path for Python should be set accordingly. Now build the shared library of TensorFlow: + ```bash bazel build -c opt --verbose_failures //tensorflow:libtensorflow_cc.so ``` -You may want to add options `--copt=-msse4.2`, `--copt=-mavx`, `--copt=-mavx2` and `--copt=-mfma` to enable SSE4.2, AVX, AVX2 and FMA SIMD accelerations, respectively. It is noted that these options should be chosen according to the CPU architecture. If the RAM becomes an issue for your machine, you may limit the RAM usage by using `--local_resources 2048,.5,1.0`. If you want to enable [oneDNN optimization](https://www.oneapi.io/blog/tensorflow-and-onednn-in-partnership/), add `--config=mkl`. + +You may want to add options `--copt=-msse4.2`, `--copt=-mavx`, `--copt=-mavx2` and `--copt=-mfma` to enable SSE4.2, AVX, AVX2 and FMA SIMD accelerations, respectively. It is noted that these options should be chosen according to the CPU architecture. If the RAM becomes an issue for your machine, you may limit the RAM usage by using `--local_resources 2048,.5,1.0`. If you want to enable [oneDNN optimization](https://www.oneapi.io/blog/tensorflow-and-onednn-in-partnership/), add `--config=mkl`. Now I assume you want to install TensorFlow in directory `$tensorflow_root`. Create the directory if it does not exist + ```bash mkdir -p $tensorflow_root ``` + Now, copy the libraries to the TensorFlow's installation directory: + ```bash mkdir -p $tensorflow_root/lib cp -d bazel-bin/tensorflow/libtensorflow_cc.so* $tensorflow_root/lib/ cp -d bazel-bin/tensorflow/libtensorflow_framework.so* $tensorflow_root/lib/ cp -d $tensorflow_root/lib/libtensorflow_framework.so.2 $tensorflow_root/lib/libtensorflow_framework.so ``` + Then copy the headers + ```bash mkdir -p $tensorflow_root/include/tensorflow rsync -avzh --exclude '_virtual_includes/' --include '*/' --include '*.h' --include '*.inc' --exclude '*' bazel-bin/ $tensorflow_root/include/ @@ -107,12 +116,15 @@ rsync -avzh --include '*/' --include '*.h' --include '*.inc' --exclude '*' bazel ``` If you've enabled oneDNN, also copy `libiomp5.so`: + ```bash cp -d bazel-out/k8-opt/bin/external/llvm_openmp/libiomp5.so $tensorflow_root/lib/ ``` # Troubleshooting + ```bash git: unknown command -C ... ``` + This may be an issue with your Git version issue. Early versions of Git do not support this command, in this case upgrading your Git to a newer version may resolve any issues. diff --git a/doc/install/install-tf.2.3.md b/doc/install/install-tf.2.3.md index e538607db0..2fc7b35f2c 100644 --- a/doc/install/install-tf.2.3.md +++ b/doc/install/install-tf.2.3.md @@ -1,5 +1,7 @@ # Install TensorFlow's C++ interface + The tensorflow's C++ interface will be compiled from the source code. Firstly one installs bazel. The bazel version 3.1.0 should be used. A full instruction of bazel installation can be found [here](https://docs.bazel.build/versions/master/install.html). + ```bash cd /some/workspace wget https://github.com/bazelbuild/bazel/releases/download/3.1.0/bazel-3.1.0-installer-linux-x86_64.sh @@ -9,6 +11,7 @@ export PATH=/some/workspace/bazel/bin:$PATH ``` Firstly get the source code of the TensorFlow + ```bash git clone https://github.com/tensorflow/tensorflow tensorflow -b v2.3.0 --depth=1 cd tensorflow @@ -75,23 +78,30 @@ Configuration finished The library path for Python should be set accordingly. Now build the shared library of tensorflow: + ```bash bazel build -c opt --verbose_failures //tensorflow:libtensorflow_cc.so ``` -You may want to add options `--copt=-msse4.2`, `--copt=-mavx`, `--copt=-mavx2` and `--copt=-mfma` to enable SSE4.2, AVX, AVX2 and FMA SIMD accelerations, respectively. It is noted that these options should be chosen according to the CPU architecture. If the RAM becomes an issue of your machine, you may limit the RAM usage by using `--local_resources 2048,.5,1.0`. + +You may want to add options `--copt=-msse4.2`, `--copt=-mavx`, `--copt=-mavx2` and `--copt=-mfma` to enable SSE4.2, AVX, AVX2 and FMA SIMD accelerations, respectively. It is noted that these options should be chosen according to the CPU architecture. If the RAM becomes an issue of your machine, you may limit the RAM usage by using `--local_resources 2048,.5,1.0`. Now I assume you want to install TensorFlow in directory `$tensorflow_root`. Create the directory if it does not exist + ```bash mkdir -p $tensorflow_root ``` + Now, copy the libraries to the tensorflow's installation directory: + ```bash mkdir -p $tensorflow_root/lib cp -d bazel-bin/tensorflow/libtensorflow_cc.so* $tensorflow_root/lib/ cp -d bazel-bin/tensorflow/libtensorflow_framework.so* $tensorflow_root/lib/ cp -d $tensorflow_root/lib/libtensorflow_framework.so.2 $tensorflow_root/lib/libtensorflow_framework.so ``` + Then copy the headers + ```bash mkdir -p $tensorflow_root/include/tensorflow rsync -avzh --exclude '_virtual_includes/' --include '*/' --include '*.h' --include '*.inc' --exclude '*' bazel-bin/ $tensorflow_root/include/ @@ -105,7 +115,9 @@ rsync -avzh --include '*/' --include '*.h' --include '*.inc' --exclude '*' bazel ``` # Troubleshooting + ```bash git: unknown command -C ... ``` + This may be an issue with your git version issue. Early versions of git do not support this command, in this case upgrading your git to a newer version may resolve any issues. diff --git a/doc/install/install-tf.2.8.md b/doc/install/install-tf.2.8.md index da1f299131..4145ba01d1 100644 --- a/doc/install/install-tf.2.8.md +++ b/doc/install/install-tf.2.8.md @@ -1,4 +1,5 @@ # Install TensorFlow's C++ interface + TensorFlow's C++ interface will be compiled from the source code. Firstly one installs Bazel. [bazelisk](https://github.com/bazelbuild/bazelisk) can be lanuched to use [bazel](https://github.com/bazelbuild/bazel). ```bash @@ -8,6 +9,7 @@ export PATH=/some/workspace/bazel/bin:$PATH ``` Firstly get the source code of the TensorFlow + ```bash git clone https://github.com/tensorflow/tensorflow tensorflow -b v2.8.0 --depth=1 cd tensorflow @@ -74,23 +76,30 @@ Configuration finished The library path for Python should be set accordingly. Now build the shared library of TensorFlow: + ```bash bazel build -c opt --verbose_failures //tensorflow:libtensorflow_cc.so ``` -You may want to add options `--copt=-msse4.2`, `--copt=-mavx`, `--copt=-mavx2` and `--copt=-mfma` to enable SSE4.2, AVX, AVX2 and FMA SIMD accelerations, respectively. It is noted that these options should be chosen according to the CPU architecture. If the RAM becomes an issue for your machine, you may limit the RAM usage by using `--local_resources 2048,.5,1.0`. If you want to enable [oneDNN optimization](https://www.oneapi.io/blog/tensorflow-and-onednn-in-partnership/), add `--config=mkl`. + +You may want to add options `--copt=-msse4.2`, `--copt=-mavx`, `--copt=-mavx2` and `--copt=-mfma` to enable SSE4.2, AVX, AVX2 and FMA SIMD accelerations, respectively. It is noted that these options should be chosen according to the CPU architecture. If the RAM becomes an issue for your machine, you may limit the RAM usage by using `--local_resources 2048,.5,1.0`. If you want to enable [oneDNN optimization](https://www.oneapi.io/blog/tensorflow-and-onednn-in-partnership/), add `--config=mkl`. Now I assume you want to install TensorFlow in directory `$tensorflow_root`. Create the directory if it does not exist + ```bash mkdir -p $tensorflow_root ``` + Now, copy the libraries to the TensorFlow's installation directory: + ```bash mkdir -p $tensorflow_root/lib cp -d bazel-bin/tensorflow/libtensorflow_cc.so* $tensorflow_root/lib/ cp -d bazel-bin/tensorflow/libtensorflow_framework.so* $tensorflow_root/lib/ cp -d $tensorflow_root/lib/libtensorflow_framework.so.2 $tensorflow_root/lib/libtensorflow_framework.so ``` + Then copy the headers + ```bash mkdir -p $tensorflow_root/include/tensorflow rsync -avzh --exclude '_virtual_includes/' --include '*/' --include '*.h' --include '*.inc' --exclude '*' bazel-bin/ $tensorflow_root/include/ @@ -104,12 +113,15 @@ rsync -avzh --include '*/' --include '*.h' --include '*.inc' --exclude '*' bazel ``` If you've enabled oneDNN, also copy `libiomp5.so`: + ```bash cp -d bazel-out/k8-opt/bin/external/llvm_openmp/libiomp5.so $tensorflow_root/lib/ ``` # Troubleshooting + ```bash git: unknown command -C ... ``` + This may be an issue with your Git version issue. Early versions of Git do not support this command, in this case upgrading your Git to a newer version may resolve any issues. diff --git a/doc/logo.md b/doc/logo.md index 420f378336..67c303f651 100644 --- a/doc/logo.md +++ b/doc/logo.md @@ -1,5 +1,5 @@ -# Logo - -DeePMD-kit logo - -The logo of DeePMD-kit is a beaver. Beavers were widely distributed in Europe and Asia but became nearly extinct due to hunting. Listed as a first-class state-protected animal in China, the population of beavers in China is less than the giant pandas. We hope that users of DeePMD-kit can enhance the awareness to protect beavers. +# Logo + +DeePMD-kit logo + +The logo of DeePMD-kit is a beaver. Beavers were widely distributed in Europe and Asia but became nearly extinct due to hunting. Listed as a first-class state-protected animal in China, the population of beavers in China is less than the giant pandas. We hope that users of DeePMD-kit can enhance the awareness to protect beavers. diff --git a/doc/model/dplr.md b/doc/model/dplr.md index 317630ebe5..ec95f9f424 100644 --- a/doc/model/dplr.md +++ b/doc/model/dplr.md @@ -13,33 +13,42 @@ In the following, we take the DPLR model for example to introduce the training a ## Theory The Deep Potential Long Range (DPLR) model adds the electrostatic energy to the total energy: + ```math E=E_{\text{DP}} + E_{\text{ele}}, ``` + where $E_{\text{DP}}$ is the short-range contribution constructed as the [standard energy model](./train-energy.md) that is fitted against $(E^\ast-E_{\text{ele}})$. $E_{\text{ele}}$ is the electrostatic energy introduced by a group of Gaussian distributions that is an approximation of the electronic structure of the system, and is calculated in Fourier space by + ```math E_{\text{ele}} = \frac{1}{2\pi V}\sum_{m \neq 0, \|m\|\leq L} \frac{\exp({-\pi ^2 m^2/\beta ^2})}{m^2}S^2(m), ``` + where $\beta$ is a freely tunable parameter that controls the spread of the Gaussians. $L$ is the cutoff in Fourier space and $S(m)$, the structure factor, is given by + ```math S(m)=\sum_i q_i e^{-2\pi \imath m \boldsymbol r_i} + \sum_n q_n e^{-2\pi \imath m \boldsymbol W_n}, ``` + where $\imath = \sqrt{-1}$ denotes the imaginary unit, $\boldsymbol r_i$ indicates ion coordinates, $q_i$ is the charge of the ion $i$, and $W_n$ is the $n$-th Wannier centroid (WC) which can be obtained from a separated [dipole model](./train-fitting-tensor.md). It can be proved that the error in the electrostatic energy introduced by the Gaussian approximations is dominated by a summation of dipole-quadrupole interactions that decay as $r^{-4}$, where $r$ is the distance between the dipole and quadrupole.[^1] -[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). +[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). ## Train a deep Wannier model for Wannier centroids We use the deep Wannier model (DW) to represent the relative position of the Wannier centroid (WC) with the atom with which it is associated. One may consult the introduction of the [dipole model](train-fitting-tensor.md) for a detailed introduction. An example input `wc.json` and a small dataset `data` for tutorial purposes can be found in + ```bash $deepmd_source_dir/examples/water/dplr/train/ ``` + It is noted that **the tutorial dataset is not enough for training a productive model**. Two settings make the training input script different from an energy training input: + ```json "fitting_net": { "type": "dipole", @@ -48,8 +57,10 @@ Two settings make the training input script different from an energy training in "seed": 1 }, ``` + The type of fitting is set to {ref}`dipole `. The dipole is associated with type 0 atoms (oxygens), by the setting `"dipole_type": [0]`. What we trained is the displacement of the WC from the corresponding oxygen atom. It shares the same training input as the atomic dipole because both are 3-dimensional vectors defined on atoms. The loss section is provided as follows + ```json "loss": { "type": "tensor", @@ -57,9 +68,11 @@ The loss section is provided as follows "pref_atomic": 1.0 }, ``` + so that the atomic dipole is trained as labels. Note that the NumPy compressed file `atomic_dipole.npy` should be provided in each dataset. The training and freezing can be started from the example directory by + ```bash dp train dw.json && dp freeze -o dw.pb ``` @@ -67,6 +80,7 @@ dp train dw.json && dp freeze -o dw.pb ## Train the DPLR model The training of the DPLR model is very similar to the standard short-range DP models. An example input script can be found in the example directory. The following section is introduced to compute the long-range energy contribution of the DPLR model, and modify the short-range DP model by this part. + ```json "modifier": { "type": "dipole_charge", @@ -77,8 +91,10 @@ The training of the DPLR model is very similar to the standard short-range DP mo "ewald_beta": 0.40 }, ``` -The {ref}`model_name ` specifies which DW model is used to predict the position of WCs. {ref}`model_charge_map ` gives the amount of charge assigned to WCs. {ref}`sys_charge_map ` provides the nuclear charge of oxygen (type 0) and hydrogen (type 1) atoms. {ref}`ewald_beta ` (unit $\text{Å}^{-1}$) gives the spread parameter controls the spread of Gaussian charges, and {ref}`ewald_h ` (unit Å) assigns the grid size of Fourier transformation. + +The {ref}`model_name ` specifies which DW model is used to predict the position of WCs. {ref}`model_charge_map ` gives the amount of charge assigned to WCs. {ref}`sys_charge_map ` provides the nuclear charge of oxygen (type 0) and hydrogen (type 1) atoms. {ref}`ewald_beta ` (unit $\text{Å}^{-1}$) gives the spread parameter controls the spread of Gaussian charges, and {ref}`ewald_h ` (unit Å) assigns the grid size of Fourier transformation. The DPLR model can be trained and frozen by (from the example directory) + ```bash dp train ener.json && dp freeze -o ener.pb ``` @@ -88,11 +104,13 @@ dp train ener.json && dp freeze -o ener.pb In MD simulations, the long-range part of the DPLR is calculated by the LAMMPS `kspace` support. Then the long-range interaction is back-propagated to atoms by DeePMD-kit. This setup is commonly used in classical molecular dynamics simulations as the "virtual site". Unfortunately, LAMMPS does not natively support virtual sites, so we have to hack the LAMMPS code, which makes the input configuration and script a little wired. An example of an input configuration file and script can be found in + ```bash $deepmd_source_dir/examples/water/dplr/lmp/ ``` We use `atom_style full` for DPLR simulations. the coordinates of the WCs are explicitly written in the configuration file. Moreover, a virtual bond is established between the oxygens and the WCs to indicate they are associated together. The configuration file containing 128 H2O molecules is thus written as + ``` 512 atoms @@ -127,13 +145,17 @@ Bonds 2 1 2 386 ... ``` + The oxygens and hydrogens are assigned with atom types 1 and 2 (corresponding to training atom types 0 and 1), respectively. The WCs are assigned with atom type 3. We want to simulate heavy water so the mass of hydrogens is set to 2. An example input script is provided in + ```bash $deepmd_source_dir/examples/water/dplr/lmp/in.lammps ``` + Here are some explanations + ```lammps # groups of real and virtual atoms group real_atom type 1 2 @@ -148,6 +170,7 @@ bond_style zero bond_coeff * special_bonds lj/coul 1 1 1 angle no ``` + Type 1 and 2 (O and H) are `real_atom`s, while type 3 (WCs) are `virtual_atom`s. The model file `ener.pb` stores both the DW and DPLR models, so the position of WCs and the energy can be inferred from it. A virtual bond type is specified by `bond_style zero`. The `special_bonds` command switches off the exclusion of intramolecular interactions. ```lammps @@ -157,19 +180,22 @@ Type 1 and 2 (O and H) are `real_atom`s, while type 3 (WCs) are `virtual_atom`s. kspace_style pppm/dplr 1e-5 kspace_modify gewald ${BETA} diff ik mesh ${KMESH} ${KMESH} ${KMESH} ``` + The long-range part is calculated by the `kspace` support of LAMMPS. The `kspace_style` `pppm/dplr` is required. The spread parameter set by variable `BETA` should be set the same as that used in training. The `KMESH` should be set dense enough so the long-range calculation is converged. ### fix dplr command **Syntax** - ``` fix ID group-ID style_name keyword value ... ``` -* ID, group-ID are documented in :doc:`fix ` command -* style_name = *dplr* -* three or more keyword/value pairs may be appended + + + +- ID, group-ID are documented in :doc:`fix ` command +- style\_name = _dplr_ +- three or more keyword/value pairs may be appended ``` keyword = *model* or *type_associate* or *bond_type* or *efield* @@ -201,6 +227,7 @@ The atom names specified in [pair_style `deepmd`](../third-party/lammps-command. If it is not set, the training parameter {ref}`type_map ` will be mapped to LAMMPS atom types. To use a time-dependent electric field, LAMMPS's `variable` feature can be utilized: + ```lammps variable EFIELD_Z equal 2*sin(2*PI*time/0.006) fix 0 all dplr model ener.pb type_associate 1 3 bond_type 1 efield 0 0 v_EFIELD_Z @@ -216,21 +243,23 @@ compute real_press all pressure real_temp fix 1 real_atom nvt temp ${TEMP} ${TEMP} ${TAU_T} fix_modify 1 temp real_temp ``` + The temperature of the system should be computed from the real atoms. The kinetic contribution in the pressure tensor is also computed from the real atoms. The thermostat is applied to only real atoms. The computed temperature and pressure of real atoms can be accessed by, e.g. + ```lammps fix thermo_print all print ${THERMO_FREQ} "$(step) $(pe) $(ke) $(etotal) $(enthalpy) $(c_real_temp) $(c_real_press) $(vol) $(c_real_press[1]) $(c_real_press[2]) $(c_real_press[3])" append thermo.out screen no title "# step pe ke etotal enthalpy temp press vol pxx pyy pzz" ``` The LAMMPS simulation can be started from the example directory by + ```bash lmp -i in.lammps ``` + If LAMMPS complains that no model file `ener.pb` exists, it can be copied from the training example directory. The MD simulation lasts for only 20 steps. If one runs a longer simulation, it will blow up, because the model is trained with a very limited dataset for very short training steps, thus is of poor quality. Another restriction that should be noted is that the energies printed at the zero steps are not correct. This is because at the zero steps the position of the WC has not been updated with the DW model. The energies printed in later steps are correct. - - [1]: https://arxiv.org/abs/2112.13327 diff --git a/doc/model/dprc.md b/doc/model/dprc.md index 4699db77d0..33dde237d7 100644 --- a/doc/model/dprc.md +++ b/doc/model/dprc.md @@ -15,6 +15,7 @@ E=E_\text{QM}(\mathbf R; \mathbf P) + E_\text{QM/MM}(\mathbf R; \mathbf P) + E_ Deep Potential - Range Correction (DPRc) was initially designed to correct the potential energy from a fast, linear-scaling low-level semiempirical QM/MM theory to a high-level ''ab initio'' QM/MM theory in a range-correction way to quantitatively correct short and mid-range non-bonded interactions leveraging the non-bonded lists routinely used in molecular dynamics simulations using molecular mechanical force fields such as AMBER. In this way, long-ranged electrostatic interactions can be modeled efficiently using the particle mesh Ewald method or its extensions for multipolar and QM/MM potentials. In a DPRc model, the switch function is modified to disable MM-MM interaction: + ```math s_\text{DPRc}(r_{ij}) = \begin{cases} @@ -22,12 +23,16 @@ In a DPRc model, the switch function is modified to disable MM-MM interaction: s(r_{ij}), &\text{otherwise}, \end{cases} ``` + where $s_\text{DPRc}(r_{ij})$ is the new switch function and $s(r_{ij})$ is the old one. This ensures the forces between MM atoms are zero, i.e. + ```math {\boldsymbol F}_{ij} = - \frac{\partial E}{\partial \boldsymbol r_{ij}} = 0, \quad i \in \text{MM} \land j \in \text{MM}. ``` + The fitting network is revised to remove energy bias from MM atoms: + ```math E_i= \begin{cases} @@ -35,10 +40,11 @@ The fitting network is revised to remove energy bias from MM atoms: \mathcal{F}_0(\mathcal{D}^i) - \mathcal{F}_0(\mathbf{0}), &\text{if $i \in \text{MM}$}, \end{cases} ``` + where $\mathbf{0}$ is a zero matrix. It is worth mentioning that usage of DPRc is not limited to its initial design for QM/MM correction and can be expanded to any similar interaction.[^1] -[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). +[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). See the [JCTC paper](https://doi.org/10.1021/acs.jctc.1c00201) for details. @@ -135,6 +141,7 @@ As described in the paper, the DPRc model only corrects $E_\text{QM}$ and $E_\te :::: {ref}`exclude_types ` can be generated by the following Python script: + ```py from itertools import combinations_with_replacement, product @@ -181,7 +188,7 @@ The DPRc model has the best practices with the [AMBER](../third-party/out-of-dee If one wants to correct from a low-level method into a full DFT level, and the system is too large to do full DFT calculation, one may try the experimental pairwise DPRc model. In a pairwise DPRc model, the total energy is divided into QM internal energy and the sum of QM/MM energy for each MM residue $l$: -$$ E = E_\text{QM} + \sum_{l} E_{\text{QM/MM},l} $$ +$$ E = E*\text{QM} + \sum*{l} E\_{\text{QM/MM},l} $$ In this way, the interaction between the QM region and each MM fragmentation can be computed and trained separately. Thus, the pairwise DPRc model is divided into two sub-[DPRc models](./dprc.md). @@ -193,32 +200,19 @@ It is noted that the [`se_atten` descriptor](./train-se-atten.md) should be used { "model": { "type": "pairwise_dprc", - "type_map": [ - "C", - "P", - "O", - "H", - "OW", - "HW" - ], + "type_map": ["C", "P", "O", "H", "OW", "HW"], "type_embedding": { - "neuron": [ - 8 - ], + "neuron": [8], "precision": "float32" }, "qm_model": { "descriptor": { "type": "se_atten_v2", "sel": 24, - "rcut_smth": 0.50, - "rcut": 9.00, + "rcut_smth": 0.5, + "rcut": 9.0, "attn_layer": 0, - "neuron": [ - 25, - 50, - 100 - ], + "neuron": [25, 50, 100], "resnet_dt": false, "axis_neuron": 12, "precision": "float32", @@ -226,21 +220,10 @@ It is noted that the [`se_atten` descriptor](./train-se-atten.md) should be used }, "fitting_net": { "type": "ener", - "neuron": [ - 240, - 240, - 240 - ], + "neuron": [240, 240, 240], "resnet_dt": true, "precision": "float32", - "atom_ener": [ - null, - null, - null, - null, - 0.0, - 0.0 - ], + "atom_ener": [null, null, null, null, 0.0, 0.0], "seed": 1 } }, @@ -248,92 +231,38 @@ It is noted that the [`se_atten` descriptor](./train-se-atten.md) should be used "descriptor": { "type": "se_atten_v2", "sel": 27, - "rcut_smth": 0.50, - "rcut": 6.00, + "rcut_smth": 0.5, + "rcut": 6.0, "attn_layer": 0, - "neuron": [ - 25, - 50, - 100 - ], + "neuron": [25, 50, 100], "resnet_dt": false, "axis_neuron": 12, "set_davg_zero": true, "exclude_types": [ - [ - 0, - 0 - ], - [ - 0, - 1 - ], - [ - 0, - 2 - ], - [ - 0, - 3 - ], - [ - 1, - 1 - ], - [ - 1, - 2 - ], - [ - 1, - 3 - ], - [ - 2, - 2 - ], - [ - 2, - 3 - ], - [ - 3, - 3 - ], - [ - 4, - 4 - ], - [ - 4, - 5 - ], - [ - 5, - 5 - ] + [0, 0], + [0, 1], + [0, 2], + [0, 3], + [1, 1], + [1, 2], + [1, 3], + [2, 2], + [2, 3], + [3, 3], + [4, 4], + [4, 5], + [5, 5] ], "precision": "float32", "seed": 1 }, "fitting_net": { "type": "ener", - "neuron": [ - 240, - 240, - 240 - ], + "neuron": [240, 240, 240], "resnet_dt": true, "seed": 1, "precision": "float32", - "atom_ener": [ - 0.0, - 0.0, - 0.0, - 0.0, - 0.0, - 0.0 - ] + "atom_ener": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0] } } } diff --git a/doc/model/overall.md b/doc/model/overall.md index f8fb2fa151..102a8fc671 100644 --- a/doc/model/overall.md +++ b/doc/model/overall.md @@ -16,17 +16,20 @@ The indices of the neighboring atoms (i.e. atoms within a certain cutoff radius) Note that the Cartesian coordinates can be either under the periodic boundary condition (PBC) or in vacuum (under the open boundary condition). The network parameters are denoted by $\boldsymbol \theta = \{\boldsymbol \theta_d, \boldsymbol \theta_f\}$, where $\boldsymbol \theta_d$ and $\boldsymbol\theta_f$ yield the network parameters of the descriptor (if any) and those of the fitting network, respectively. From the above equation, one may compute the global property of the system by + ```math \boldsymbol y = \sum_{i=1}^N \boldsymbol y_i, ``` + where $N$ is the number of atoms in a frame. For example, if $y_i$ represents the potential energy contribution of atom $i$, then $y$ gives the total potential energy of the frame.[^1] -[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). +[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). ## Instructions A model has two parts, a descriptor that maps atomic configuration to a set of symmetry invariant features, and a fitting net that takes descriptor as input and predicts the atomic contribution to the target physical property. It's defined in the {ref}`model ` section of the `input.json`, for example, + ```json "model": { "type_map": ["O", "H"], @@ -38,11 +41,13 @@ A model has two parts, a descriptor that maps atomic configuration to a set of s } } ``` + The two subsections, {ref}`descriptor ` and {ref}`fitting_net `, define the descriptor and the fitting net, respectively. The {ref}`type_map ` is optional, which provides the element names (but not necessarily same as the actual name of the element) of the corresponding atom types. A water model, as in this example, has two kinds of atoms. The atom types are internally recorded as integers, e.g., `0` for oxygen and `1` for hydrogen here. A mapping from the atom type to their names is provided by {ref}`type_map `. DeePMD-kit implements the following descriptors: + 1. [`se_e2_a`](train-se-e2-a.md): DeepPot-SE constructed from all information (both angular and radial) of atomic configurations. The embedding takes the distance between atoms as input. 2. [`se_e2_r`](train-se-e2-r.md): DeepPot-SE constructed from radial information of atomic configurations. The embedding takes the distance between atoms as input. 3. [`se_e3`](train-se-e3.md): DeepPot-SE constructed from all information (both angular and radial) of atomic configurations. The embedding takes angles between two neighboring atoms as input. @@ -51,6 +56,7 @@ DeePMD-kit implements the following descriptors: 6. [`hybrid`](train-hybrid.md): Concate a list of descriptors to form a new descriptor. The fitting of the following physical properties is supported + 1. [`ener`](train-energy.md): Fit the energy of the system. The force (derivative with atom positions) and the virial (derivative with the box tensor) can also be trained. 2. [`dipole`](train-fitting-tensor.md): The dipole moment. 3. [`polar`](train-fitting-tensor.md): The polarizability. diff --git a/doc/model/pairtab.md b/doc/model/pairtab.md index fee4d754a6..c8763705f7 100644 --- a/doc/model/pairtab.md +++ b/doc/model/pairtab.md @@ -5,17 +5,23 @@ ::: ## Theory + In applications like the radiation damage simulation, the interatomic distance may become too close, so that the DFT calculations fail. In such cases, the DP model that is an approximation of the DFT potential energy surface is usually replaced by an empirical potential, like the Ziegler-Biersack-Littmark (ZBL) screened nuclear repulsion potential in the radiation damage simulations. The DeePMD-kit package supports the interpolation between DP and an empirical pairwise potential + ```math E_i = (1-w_i) E_i^{\mathrm{DP}} + w_i (E_i^0 + E_i^{\mathrm{pair}}), ``` + where the $w_i$ is the interpolation weight and the $E_i^{\mathrm{pair}} $ is the atomic contribution due to the pairwise potential $u^{\mathrm{pair}}(r)$, i.e. + ```math E_i^{\mathrm{pair}} = \sum_{j\in n(i)} u^{\mathrm{pair}}(r_{ij}). ``` + The interpolation weight $w_i$ is defined by + ```math w_i = \begin{cases} @@ -24,19 +30,22 @@ The interpolation weight $w_i$ is defined by 0, & \sigma_i \geq r_b, \end{cases} ``` + where $u_i = (\sigma_i - r_a ) / (r_b - r_a)$. $E_i^0$ is the atom energy bias. In the range $[r_a, r_b]$, the DP model smoothly switched off and the pairwise potential smoothly switched on from $r_b$ to $r_a$. The $\sigma_i$ is the softmin of the distance between atom $i$ and its neighbors, + ```math \sigma_i = \dfrac {\sum\limits_{j\in n(i)} r_{ij} e^{-r_{ij} / \alpha_s}} {\sum\limits_{j\in n(i)} e^{-r_{ij} / \alpha_s}}, ``` + where the scale $\alpha_s$ is a tunable scale of the interatomic distance $r_{ij}$. The pairwise potential $u^{\textrm{pair}}(r)$ is defined by a user-defined table that provides the value of $u^{\textrm{pair}}$ on an evenly discretized grid from 0 to the cutoff distance.[^1] -[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). +[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). DeePMD-kit also supports combination with a pairwise potential: diff --git a/doc/model/sel.md b/doc/model/sel.md index f4a3cf6c09..8455c242a9 100644 --- a/doc/model/sel.md +++ b/doc/model/sel.md @@ -5,9 +5,11 @@ All descriptors require to set `sel`, which means the expected maximum number of `sel` should not be too large or too small. If `sel` is too large, the computing will become much slower and cost more memory. If `sel` is not enough, the energy will be not conserved, making the accuracy of the model worse. To determine a proper `sel`, one can calculate the neighbor stat of the training data before training: + ```sh dp neighbor-stat -s data -r 6.0 -t O H ``` + where `data` is the directory of data, `6.0` is the cutoff radius, and `O` and `H` is the type map. The program will give the `max_nbor_size`. For example, `max_nbor_size` of the water example is `[38, 72]`, meaning an atom may have 38 O neighbors and 72 H neighbors in the training data. The `sel` should be set to a higher value than that of the training data, considering there may be some extreme geometries during MD simulations. As a result, we set `sel` to `[46, 92]` in the water example. diff --git a/doc/model/train-energy-spin.md b/doc/model/train-energy-spin.md index e0b3968c09..3eb589590b 100644 --- a/doc/model/train-energy-spin.md +++ b/doc/model/train-energy-spin.md @@ -9,6 +9,7 @@ In this section, we will take `$deepmd_source_dir/examples/NiO/se_e2_a/input.jso ## Spin The construction of the fitting net is give by section {ref}`spin ` + ```json "spin" : { "use_spin": [true, false], @@ -16,9 +17,10 @@ The construction of the fitting net is give by section {ref}`spin ` "spin_norm": [1.2737], }, ``` -* {ref}`use_spin ` determines whether to turn on the magnetism of the atoms.The index of this option matches option `type_map `. -* {ref}`virtual_len ` specifies the distance between virtual atom and the belonging real atom. -* {ref}`spin_norm ` gives the magnitude of the magnetic moment for each magnatic atom. + +- {ref}`use_spin ` determines whether to turn on the magnetism of the atoms.The index of this option matches option `type_map `. +- {ref}`virtual_len ` specifies the distance between virtual atom and the belonging real atom. +- {ref}`spin_norm ` gives the magnitude of the magnetic moment for each magnatic atom. ## Spin Loss @@ -33,11 +35,13 @@ The prefectors may not be a constant, rather it changes linearly with the learni $$p_{fr}(t) = p_{fr}^0 \frac{ \alpha(t) }{ \alpha(0) } + p_{fr}^\infty ( 1 - \frac{ \alpha(t) }{ \alpha(0) })$$ where $\alpha(t)$ denotes the learning rate at step $t$. $p_{fr}^0$ and $p_{fr}^\infty$ specifies the $p_f$ at the start of the training and at the limit of $t \to \infty$ (set by {ref}`start_pref_fr ` and {ref}`limit_pref_f `, respectively), i.e. + ```math pref_fr(t) = start_pref_fr * ( lr(t) / start_lr ) + limit_pref_fr * ( 1 - lr(t) / start_lr ) ``` The {ref}`loss ` section in the `input.json` is + ```json "loss" :{ "type": "ener_spin", @@ -51,6 +55,7 @@ The {ref}`loss ` section in the `input.json` is "limit_pref_v": 0, }, ``` + The options {ref}`start_pref_e `, {ref}`limit_pref_e `, {ref}`start_pref_fr `, {ref}`limit_pref_fm `, {ref}`start_pref_v ` and {ref}`limit_pref_v ` determine the start and limit prefactors of energy, atomic force, magnatic force and virial, respectively. If one does not want to train with virial, then he/she may set the virial prefactors {ref}`start_pref_v ` and {ref}`limit_pref_v ` to 0. diff --git a/doc/model/train-energy.md b/doc/model/train-energy.md index bfe304b5d2..c1da1f4c1f 100644 --- a/doc/model/train-energy.md +++ b/doc/model/train-energy.md @@ -8,63 +8,79 @@ In this section, we will take `$deepmd_source_dir/examples/water/se_e2_a/input.j ## Theory -In the DP model, we let the fitting network $\mathcal{F}_ 0$ maps the descriptor $\mathcal{D}^i$ to a scalar, where the subscript $0$ means that the output is a zero-order tensor (i.e. scalar). The model can then be used to predict the total potential energy of the system by +In the DP model, we let the fitting network $\mathcal{F}_ 0$ maps the descriptor $\mathcal{D}^i$ to a scalar, where the subscript $0$ means that the output is a zero-order tensor (i.e. scalar). The model can then be used to predict the total potential energy of the system by + ```math E = \sum_i E_i = \sum_i \mathcal F_0 (\mathcal D^i), ``` + where the output of the fitting network is treated as the atomic potential energy contribution, i.e. $E_i$. The output scalar can also be treated as other scalar properties defined on an atom, for example, the partial charge of atom $i$. -In some cases, atomic-specific or frame-specific parameters, such as electron temperature, may be treated as extra input to the fitting network. +In some cases, atomic-specific or frame-specific parameters, such as electron temperature, may be treated as extra input to the fitting network. We denote the atomic and frame-specific parameters by $\boldsymbol{P}^i\in \mathbb{R}^{N_p}$ (with $N_p$ being the dimension) and $\boldsymbol{Q}\in \mathbb{R}^{N_q}$ (with $N_q$ being the dimension), respectively. + ```math E_i=\mathcal{F}_0(\{\mathcal{D}^i, \boldsymbol{P}^i, \boldsymbol Q\}). ``` The atomic force $\boldsymbol{F}_ {i}$ and the virial tensor $\boldsymbol{\Xi} = (\Xi_{\alpha\beta})$ (if PBC is applied) can be derived from the potential energy $E$: + ```math F_{i,\alpha}=-\frac{\partial E}{\partial r_{i,\alpha}}, ``` + ```math \Xi_{\alpha\beta}=-\sum_{\gamma} \frac{\partial E}{\partial h_{\gamma\alpha}} h_{\gamma\beta}, ``` + where $r_{i,\alpha}$ and $F_{i,\alpha}$ denotes the $\alpha$-th component of the coordinate and force of atom $i$. $h_{\alpha\beta}$ is the $\beta$-th component of the $\alpha$-th basis vector of the simulation region. The properties $\eta$ of the energy loss function could be energy $E$, force $\boldsymbol{F}$, virial $\boldsymbol{\Xi}$, relative energy $\Delta E$, or any combination among them, and the loss functions of them are + ```math L_E(\boldsymbol{x};\boldsymbol{\theta})=\frac{1}{N}(E(\boldsymbol{x};\boldsymbol{\theta})-E^*)^2, ``` + ```math L_F(\boldsymbol{x};\boldsymbol{\theta})=\frac{1}{3N}\sum_{k=1}^{N}\sum_{\alpha=1}^3(F_{k,\alpha}(\boldsymbol{x};\boldsymbol{\theta})-F_{k,\alpha}^*)^2, ``` + ```math L_\Xi(\boldsymbol{x};\boldsymbol{\theta})=\frac{1}{9N}\sum_{\alpha,\beta=1}^{3}(\Xi_{\alpha\beta}(\boldsymbol{x};\boldsymbol{\theta})-\Xi_{\alpha\beta}^*)^2, ``` + ```math L_{\Delta E}(\boldsymbol{x};\boldsymbol{\theta})=\frac{1}{N}({\Delta E}(\boldsymbol{x};\boldsymbol{\theta})-{\Delta E}^*)^2, ``` + where $F_{k,\alpha}$ is the $\alpha$-th component of the force on atom $k$, and the superscript $\ast$ indicates the label of the property that should be provided in advance. Using $N$ ensures that each loss of fitting property is averaged over atomic contributions before they contribute to the total loss by weight. If part of atoms is more important than others, for example, certain atoms play an essential role when calculating free energy profiles or kinetic isotope effects, the MSE of atomic forces with prefactors $q_{k}$ can also be used as the loss function: + ```math L_F^p(\mathbf{x};\boldsymbol{\theta})=\frac{1}{3N}\sum_{k=1}^{N} \sum_{\alpha} q_{k} (F_{k,\alpha}(\mathbf{x};\boldsymbol{\theta})-F_{k,\alpha}^*)^2. ``` + The atomic forces with larger prefactors will be fitted more accurately than those in other atoms. If some forces are quite large, for example, forces can be greater than 60 eV/Å in high-temperature reactive simulations, one may also prefer the force loss is relative to the magnitude: + ```math L^r_F(\boldsymbol{x};\boldsymbol{\theta})=\frac{1}{3N}\sum_{k=1}^{N}\sum_\alpha \left(\frac{F_{k,\alpha}(\boldsymbol{x};\boldsymbol{\theta})-F_{k,\alpha}^*}{\lvert\boldsymbol{F}^\ast_k\lvert + \nu}\right)^2. ``` + where $\nu$ is a small constant used to protect an atom where the magnitude of $\boldsymbol{F}^\ast_k$ is small from having a large $L^r_F$. Benefiting from the relative force loss, small forces can be fitted more accurately.[^1] -[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). +[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). ## The fitting network The construction of the fitting net is given by section {ref}`fitting_net ` + ```json "fitting_net" : { "neuron": [240, 240, 240], @@ -72,9 +88,10 @@ The construction of the fitting net is given by section {ref}`fitting_net ` specifies the size of the fitting net. If two neighboring layers are of the same size, then a [ResNet architecture](https://arxiv.org/abs/1512.03385) is built between them. -* If the option {ref}`resnet_dt ` is set to `true`, then a timestep is used in the ResNet. -* {ref}`seed ` gives the random seed that is used to generate random numbers when initializing the model parameters. + +- {ref}`neuron ` specifies the size of the fitting net. If two neighboring layers are of the same size, then a [ResNet architecture](https://arxiv.org/abs/1512.03385) is built between them. +- If the option {ref}`resnet_dt ` is set to `true`, then a timestep is used in the ResNet. +- {ref}`seed ` gives the random seed that is used to generate random numbers when initializing the model parameters. ## Loss @@ -87,11 +104,13 @@ where $L_e$, $L_f$, and $L_v$ denote the loss in energy, forces and virials, res $$p_f(t) = p_f^0 \frac{ \alpha(t) }{ \alpha(0) } + p_f^\infty ( 1 - \frac{ \alpha(t) }{ \alpha(0) })$$ where $\alpha(t)$ denotes the learning rate at step $t$. $p_f^0$ and $p_f^\infty$ specifies the $p_f$ at the start of the training and the limit of $t \to \infty$ (set by {ref}`start_pref_f ` and {ref}`limit_pref_f `, respectively), i.e. + ```math pref_f(t) = start_pref_f * ( lr(t) / start_lr ) + limit_pref_f * ( 1 - lr(t) / start_lr ) ``` The {ref}`loss ` section in the `input.json` is + ```json "loss" : { "start_pref_e": 0.02, @@ -102,6 +121,7 @@ The {ref}`loss ` section in the `input.json` is "limit_pref_v": 0 } ``` + The options {ref}`start_pref_e `, {ref}`limit_pref_e `, {ref}`start_pref_f `, {ref}`limit_pref_f `, {ref}`start_pref_v ` and {ref}`limit_pref_v ` determine the start and limit prefactors of energy, force and virial, respectively. If one does not want to train with virial, then he/she may set the virial prefactors {ref}`start_pref_v ` and {ref}`limit_pref_v ` to 0. diff --git a/doc/model/train-fitting-dos.md b/doc/model/train-fitting-dos.md index b74ab3acf7..7b68525a45 100644 --- a/doc/model/train-fitting-dos.md +++ b/doc/model/train-fitting-dos.md @@ -36,9 +36,9 @@ The JSON of `dos` type should be provided like }, ``` -- `type` specifies which type of fitting net should be used. It should be `dos`. -- `numb_dos` specifies the length of output vector (density of states), which the same as the `NEDOS` set in VASP software, this argument defines the output length of the neural network. We note that the length of `dos` provided in training set should be the same. -- The rest arguments have the same meaning as they do in `ener` mode. +- `type` specifies which type of fitting net should be used. It should be `dos`. +- `numb_dos` specifies the length of output vector (density of states), which the same as the `NEDOS` set in VASP software, this argument defines the output length of the neural network. We note that the length of `dos` provided in training set should be the same. +- The rest arguments have the same meaning as they do in `ener` mode. ## Loss @@ -66,13 +66,12 @@ The loss section should be provided like }, ``` -- {ref}`type ` should be written as `dos` as a distinction from `ener` mode. -- `pref_dos` and `pref_ados`, respectively specify the weight of global and atomic loss. If set to 0, the corresponding label will not be included in the training process. -- We also provides a combination training of vector and its cumulative distribution function `cdf`, which can be defined as +- {ref}`type ` should be written as `dos` as a distinction from `ener` mode. +- `pref_dos` and `pref_ados`, respectively specify the weight of global and atomic loss. If set to 0, the corresponding label will not be included in the training process. +- We also provides a combination training of vector and its cumulative distribution function `cdf`, which can be defined as $$D(\epsilon) = \int_{e_{min}}^{\epsilon} g(\epsilon')d\epsilon'$$ - ## Training Data Preparation The global label should be named `dos.npy/raw`, while the atomic label should be named `atomic_dos.npy/raw`. If wrongly named, DP will report an error. diff --git a/doc/model/train-fitting-tensor.md b/doc/model/train-fitting-tensor.md index 0c9c0f492c..4d5cb22707 100644 --- a/doc/model/train-fitting-tensor.md +++ b/doc/model/train-fitting-tensor.md @@ -1,236 +1,243 @@ -# Fit `tensor` like `Dipole` and `Polarizability` {{ tensorflow_icon }} {{ pytorch_icon }} {{ dpmodel_icon }} - -:::{note} -**Supported backends**: TensorFlow {{ tensorflow_icon }} {{ pytorch_icon }} {{ dpmodel_icon }} -::: - -Unlike `energy`, which is a scalar, one may want to fit some high dimensional physical quantity, like `dipole` (vector) and `polarizability` (matrix, shorted as `polar`). Deep Potential has provided different APIs to do this. In this example, we will show you how to train a model to fit a water system. A complete training input script of the examples can be found in - -::::{tab-set} - -:::{tab-item} TensorFlow {{ tensorflow_icon }} - -```bash -$deepmd_source_dir/examples/water_tensor/dipole/dipole_input.json -$deepmd_source_dir/examples/water_tensor/polar/polar_input.json -``` - -::: - -:::{tab-item} PyTorch {{ pytorch_icon }} - -```bash -$deepmd_source_dir/examples/water_tensor/dipole/dipole_input_torch.json -$deepmd_source_dir/examples/water_tensor/polar/polar_input_torch.json -``` - -::: - -:::: - -The training and validation data are also provided our examples. But note that **the data provided along with the examples are of limited amount, and should not be used to train a production model.** - -Similar to the `input.json` used in `ener` mode, training JSON is also divided into {ref}`model `, {ref}`learning_rate `, {ref}`loss ` and {ref}`training `. Most keywords remain the same as `ener` mode, and their meaning can be found [here](train-se-e2-a.md). To fit a tensor, one needs to modify {ref}`model/fitting_net ` and {ref}`loss `. - -## Theory - -To represent the first-order tensorial properties (i.e. vector properties), we let the fitting network, denoted by $\mathcal F_{1}$, output an $M$-dimensional vector; then we have the representation, - -```math -(T_i^{(1)})_\alpha = -\frac{1}{N_c} -\sum_{j=1}^{N_c}\sum_{m=1}^M (\mathcal G^i)_{jm} (\mathcal R^i)_{j,\alpha+1} -(\mathcal F_{1}(\mathcal D^i))_m, \ \alpha=1,2,3. -``` -We let the fitting network $\mathcal F_{2}$ output an $M$-dimensional vector, and the second-order tensorial properties (matrix properties) are formulated as -```math -(T_i^{(2)})_{\alpha\beta} = -\frac{1}{N_c^2} -\sum_{j=1}^{N_c}\sum_{k=1}^{N_c}\sum_{m=1}^M -(\mathcal G^i)_{jm} -(\mathcal R^i)_{j,\alpha+1} -(\mathcal R^i)_{k,\beta+1} -(\mathcal G^i)_{km} -(\mathcal F_{2}(\mathcal D^i))_m, -\ \alpha,\beta=1,2,3, -``` - -where $\mathcal{G}^i$ and $\mathcal{R}^i$ can be found in [`se_e2_a`](./train-se-e2-a.md). -Thus, the tensor fitting network requires the descriptor to have the same or similar form as the DeepPot-SE descriptor. -$\mathcal{F}_1$ and $\mathcal F_2$ are the neural network functions. -The total tensor $\boldsymbol{T}$ (total dipole $\boldsymbol{T}^{(1)}$ or total polarizability $\boldsymbol{T}^{(2)}$) is the sum of the atomic tensor: -```math - \boldsymbol{T} = \sum_i \boldsymbol{T}_i. -``` -The tensorial models can be used to calculate IR spectrum and Raman spectrum.[^1] - -[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). - -## The fitting Network - -The {ref}`fitting_net ` section tells DP which fitting net to use. - -::::{tab-set} - -:::{tab-item} TensorFlow {{ tensorflow_icon }} - -The JSON of `dipole` type should be provided like - -```json - "fitting_net" : { - "type": "dipole", - "sel_type": [0], - "neuron": [100,100,100], - "resnet_dt": true, - "seed": 1, - }, -``` - -The JSON of `polar` type should be provided like - -```json - "fitting_net" : { - "type": "polar", - "sel_type": [0], - "neuron": [100,100,100], - "resnet_dt": true, - "seed": 1, - }, -``` - -- `type` specifies which type of fitting net should be used. It should be either `dipole` or `polar`. Note that `global_polar` mode in version 1.x is already **deprecated** and is merged into `polar`. To specify whether a system is global or atomic, please see [here](train-se-e2-a.md). -- `sel_type` is a list specifying which type of atoms have the quantity you want to fit. For example, in the water system, `sel_type` is `[0]` since `0` represents atom `O`. If left unset, all types of atoms will be fitted. -- The rest arguments have the same meaning as they do in `ener` mode. - -::: - -:::{tab-item} PyTorch {{ pytorch_icon }} - -The JSON of `dipole` type should be provided like -```json - "atom_exclude_types": [ - 1 - ], - "fitting_net" : { - "type": "dipole", - "neuron": [100,100,100], - "resnet_dt": true, - "seed": 1, - }, -``` - -The JSON of `polar` type should be provided like - -```json - "atom_exclude_types": [ - 1 - ], - "fitting_net" : { - "type": "polar", - "neuron": [100,100,100], - "resnet_dt": true, - "seed": 1, - }, -``` -- `type` specifies which type of fitting net should be used. It should be either `dipole` or `polar`. Note that `global_polar` mode in version 1.x is already **deprecated** and is merged into `polar`. To specify whether a system is global or atomic, please see [here](train-se-e2-a.md). -- `atom_exclude_types` is a list specifying the which type of atoms have the quantity you want to set to zero. For example, in the water system, `atom_exclude_types` is `[1]` since `1` represents atom `H`. -- The rest arguments have the same meaning as they do in `ener` mode. -::: - -:::: - - - -## Loss - -DP supports a combinational training of the global system (only a global `tensor` label, i.e. dipole or polar, is provided in a frame) and atomic system (labels for **each** atom included in `sel_type`/ not included in `atom_exclude_types` are provided). In a global system, each frame has just **one** `tensor` label. For example, when fitting `polar`, each frame will just provide a `1 x 9` vector which gives the elements of the polarizability tensor of that frame in order XX, XY, XZ, YX, YY, YZ, XZ, ZY, ZZ. By contrast, in an atomic system, each atom in `sel_type` has a `tensor` label. For example, when fitting a dipole, each frame will provide a `#sel_atom x 3` matrices, where `#sel_atom` is the number of atoms whose type are in `sel_type`. - -The {ref}`loss ` section tells DP the weight of these two kinds of loss, i.e. - -```python -loss = pref * global_loss + pref_atomic * atomic_loss -``` - -The loss section should be provided like - -```json - "loss" : { - "type": "tensor", - "pref": 1.0, - "pref_atomic": 1.0 - }, -``` - -- {ref}`type ` should be written as `tensor` as a distinction from `ener` mode. -- {ref}`pref ` and {ref}`pref_atomic ` respectively specify the weight of global loss and atomic loss. It can not be left unset. If set to 0, the corresponding label will NOT be included in the training process. - -## Training Data Preparation - -In tensor mode, the identification of the label's type (global or atomic) is derived from the file name. The global label should be named `dipole.npy/raw` or `polarizability.npy/raw`, while the atomic label should be named `atomic_dipole.npy/raw` or `atomic_polarizability.npy/raw`. If wrongly named, DP will report an error - -```bash -ValueError: cannot reshape array of size xxx into shape (xx,xx). This error may occur when your label mismatch it's name, i.e. you might store global tensor in `atomic_tensor.npy` or atomic tensor in `tensor.npy`. -``` - -In this case, please check the file name of the label. - -## Train the Model - -The training command is the same as `ener` mode, i.e. - -::::{tab-set} - -:::{tab-item} TensorFlow {{ tensorflow_icon }} - -```bash -dp train input.json -``` -::: - -:::{tab-item} PyTorch {{ pytorch_icon }} - -```bash -dp --pt train input.json -``` -::: - -:::: - - -The detailed loss can be found in `lcurve.out`: - -``` -# step rmse_val rmse_trn rmse_lc_val rmse_lc_trn rmse_gl_val rmse_gl_trn lr - 0 8.34e+00 8.26e+00 8.34e+00 8.26e+00 0.00e+00 0.00e+00 1.0e-02 - 100 3.51e-02 8.55e-02 0.00e+00 8.55e-02 4.38e-03 0.00e+00 5.0e-03 - 200 4.77e-02 5.61e-02 0.00e+00 5.61e-02 5.96e-03 0.00e+00 2.5e-03 - 300 5.68e-02 1.47e-02 0.00e+00 0.00e+00 7.10e-03 1.84e-03 1.3e-03 - 400 3.73e-02 3.48e-02 1.99e-02 0.00e+00 2.18e-03 4.35e-03 6.3e-04 - 500 2.77e-02 5.82e-02 1.08e-02 5.82e-02 2.11e-03 0.00e+00 3.2e-04 - 600 2.81e-02 5.43e-02 2.01e-02 0.00e+00 1.01e-03 6.79e-03 1.6e-04 - 700 2.97e-02 3.28e-02 2.03e-02 0.00e+00 1.17e-03 4.10e-03 7.9e-05 - 800 2.25e-02 6.19e-02 9.05e-03 0.00e+00 1.68e-03 7.74e-03 4.0e-05 - 900 3.18e-02 5.54e-02 9.93e-03 5.54e-02 2.74e-03 0.00e+00 2.0e-05 - 1000 2.63e-02 5.02e-02 1.02e-02 5.02e-02 2.01e-03 0.00e+00 1.0e-05 - 1100 3.27e-02 5.89e-02 2.13e-02 5.89e-02 1.43e-03 0.00e+00 5.0e-06 - 1200 2.85e-02 2.42e-02 2.85e-02 0.00e+00 0.00e+00 3.02e-03 2.5e-06 - 1300 3.47e-02 5.71e-02 1.07e-02 5.71e-02 3.00e-03 0.00e+00 1.3e-06 - 1400 3.13e-02 5.76e-02 3.13e-02 5.76e-02 0.00e+00 0.00e+00 6.3e-07 - 1500 3.34e-02 1.11e-02 2.09e-02 0.00e+00 1.57e-03 1.39e-03 3.2e-07 - 1600 3.11e-02 5.64e-02 3.11e-02 5.64e-02 0.00e+00 0.00e+00 1.6e-07 - 1700 2.97e-02 5.05e-02 2.97e-02 5.05e-02 0.00e+00 0.00e+00 7.9e-08 - 1800 2.64e-02 7.70e-02 1.09e-02 0.00e+00 1.94e-03 9.62e-03 4.0e-08 - 1900 3.28e-02 2.56e-02 3.28e-02 0.00e+00 0.00e+00 3.20e-03 2.0e-08 - 2000 2.59e-02 5.71e-02 1.03e-02 5.71e-02 1.94e-03 0.00e+00 1.0e-08 -``` - -One may notice that in each step, some of the local loss and global loss will be `0.0`. This is because our training data and validation data consist of the global system and atomic system, i.e. -``` - --training_data - >atomic_system - >global_system - --validation_data - >atomic_system - >global_system -``` -During training, at each step when the `lcurve.out` is printed, the system used for evaluating the training (validation) error may be either with only global or only atomic labels, thus the corresponding atomic or global errors are missing and are printed as zeros. +# Fit `tensor` like `Dipole` and `Polarizability` {{ tensorflow_icon }} {{ pytorch_icon }} {{ dpmodel_icon }} + +:::{note} +**Supported backends**: TensorFlow {{ tensorflow_icon }} {{ pytorch_icon }} {{ dpmodel_icon }} +::: + +Unlike `energy`, which is a scalar, one may want to fit some high dimensional physical quantity, like `dipole` (vector) and `polarizability` (matrix, shorted as `polar`). Deep Potential has provided different APIs to do this. In this example, we will show you how to train a model to fit a water system. A complete training input script of the examples can be found in + +::::{tab-set} + +:::{tab-item} TensorFlow {{ tensorflow_icon }} + +```bash +$deepmd_source_dir/examples/water_tensor/dipole/dipole_input.json +$deepmd_source_dir/examples/water_tensor/polar/polar_input.json +``` + +::: + +:::{tab-item} PyTorch {{ pytorch_icon }} + +```bash +$deepmd_source_dir/examples/water_tensor/dipole/dipole_input_torch.json +$deepmd_source_dir/examples/water_tensor/polar/polar_input_torch.json +``` + +::: + +:::: + +The training and validation data are also provided our examples. But note that **the data provided along with the examples are of limited amount, and should not be used to train a production model.** + +Similar to the `input.json` used in `ener` mode, training JSON is also divided into {ref}`model `, {ref}`learning_rate `, {ref}`loss ` and {ref}`training `. Most keywords remain the same as `ener` mode, and their meaning can be found [here](train-se-e2-a.md). To fit a tensor, one needs to modify {ref}`model/fitting_net ` and {ref}`loss `. + +## Theory + +To represent the first-order tensorial properties (i.e. vector properties), we let the fitting network, denoted by $\mathcal F_{1}$, output an $M$-dimensional vector; then we have the representation, + +```math +(T_i^{(1)})_\alpha = +\frac{1}{N_c} +\sum_{j=1}^{N_c}\sum_{m=1}^M (\mathcal G^i)_{jm} (\mathcal R^i)_{j,\alpha+1} +(\mathcal F_{1}(\mathcal D^i))_m, \ \alpha=1,2,3. +``` + +We let the fitting network $\mathcal F_{2}$ output an $M$-dimensional vector, and the second-order tensorial properties (matrix properties) are formulated as + +```math +(T_i^{(2)})_{\alpha\beta} = +\frac{1}{N_c^2} +\sum_{j=1}^{N_c}\sum_{k=1}^{N_c}\sum_{m=1}^M +(\mathcal G^i)_{jm} +(\mathcal R^i)_{j,\alpha+1} +(\mathcal R^i)_{k,\beta+1} +(\mathcal G^i)_{km} +(\mathcal F_{2}(\mathcal D^i))_m, +\ \alpha,\beta=1,2,3, +``` + +where $\mathcal{G}^i$ and $\mathcal{R}^i$ can be found in [`se_e2_a`](./train-se-e2-a.md). +Thus, the tensor fitting network requires the descriptor to have the same or similar form as the DeepPot-SE descriptor. +$\mathcal{F}_1$ and $\mathcal F_2$ are the neural network functions. +The total tensor $\boldsymbol{T}$ (total dipole $\boldsymbol{T}^{(1)}$ or total polarizability $\boldsymbol{T}^{(2)}$) is the sum of the atomic tensor: + +```math + \boldsymbol{T} = \sum_i \boldsymbol{T}_i. +``` + +The tensorial models can be used to calculate IR spectrum and Raman spectrum.[^1] + +[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). + +## The fitting Network + +The {ref}`fitting_net ` section tells DP which fitting net to use. + +::::{tab-set} + +:::{tab-item} TensorFlow {{ tensorflow_icon }} + +The JSON of `dipole` type should be provided like + +```json + "fitting_net" : { + "type": "dipole", + "sel_type": [0], + "neuron": [100,100,100], + "resnet_dt": true, + "seed": 1, + }, +``` + +The JSON of `polar` type should be provided like + +```json + "fitting_net" : { + "type": "polar", + "sel_type": [0], + "neuron": [100,100,100], + "resnet_dt": true, + "seed": 1, + }, +``` + +- `type` specifies which type of fitting net should be used. It should be either `dipole` or `polar`. Note that `global_polar` mode in version 1.x is already **deprecated** and is merged into `polar`. To specify whether a system is global or atomic, please see [here](train-se-e2-a.md). +- `sel_type` is a list specifying which type of atoms have the quantity you want to fit. For example, in the water system, `sel_type` is `[0]` since `0` represents atom `O`. If left unset, all types of atoms will be fitted. +- The rest arguments have the same meaning as they do in `ener` mode. + +::: + +:::{tab-item} PyTorch {{ pytorch_icon }} + +The JSON of `dipole` type should be provided like + +```json + "atom_exclude_types": [ + 1 + ], + "fitting_net" : { + "type": "dipole", + "neuron": [100,100,100], + "resnet_dt": true, + "seed": 1, + }, +``` + +The JSON of `polar` type should be provided like + +```json + "atom_exclude_types": [ + 1 + ], + "fitting_net" : { + "type": "polar", + "neuron": [100,100,100], + "resnet_dt": true, + "seed": 1, + }, +``` + +- `type` specifies which type of fitting net should be used. It should be either `dipole` or `polar`. Note that `global_polar` mode in version 1.x is already **deprecated** and is merged into `polar`. To specify whether a system is global or atomic, please see [here](train-se-e2-a.md). +- `atom_exclude_types` is a list specifying the which type of atoms have the quantity you want to set to zero. For example, in the water system, `atom_exclude_types` is `[1]` since `1` represents atom `H`. +- The rest arguments have the same meaning as they do in `ener` mode. + ::: + +:::: + +## Loss + +DP supports a combinational training of the global system (only a global `tensor` label, i.e. dipole or polar, is provided in a frame) and atomic system (labels for **each** atom included in `sel_type`/ not included in `atom_exclude_types` are provided). In a global system, each frame has just **one** `tensor` label. For example, when fitting `polar`, each frame will just provide a `1 x 9` vector which gives the elements of the polarizability tensor of that frame in order XX, XY, XZ, YX, YY, YZ, XZ, ZY, ZZ. By contrast, in an atomic system, each atom in `sel_type` has a `tensor` label. For example, when fitting a dipole, each frame will provide a `#sel_atom x 3` matrices, where `#sel_atom` is the number of atoms whose type are in `sel_type`. + +The {ref}`loss ` section tells DP the weight of these two kinds of loss, i.e. + +```python +loss = pref * global_loss + pref_atomic * atomic_loss +``` + +The loss section should be provided like + +```json + "loss" : { + "type": "tensor", + "pref": 1.0, + "pref_atomic": 1.0 + }, +``` + +- {ref}`type ` should be written as `tensor` as a distinction from `ener` mode. +- {ref}`pref ` and {ref}`pref_atomic ` respectively specify the weight of global loss and atomic loss. It can not be left unset. If set to 0, the corresponding label will NOT be included in the training process. + +## Training Data Preparation + +In tensor mode, the identification of the label's type (global or atomic) is derived from the file name. The global label should be named `dipole.npy/raw` or `polarizability.npy/raw`, while the atomic label should be named `atomic_dipole.npy/raw` or `atomic_polarizability.npy/raw`. If wrongly named, DP will report an error + +```bash +ValueError: cannot reshape array of size xxx into shape (xx,xx). This error may occur when your label mismatch it's name, i.e. you might store global tensor in `atomic_tensor.npy` or atomic tensor in `tensor.npy`. +``` + +In this case, please check the file name of the label. + +## Train the Model + +The training command is the same as `ener` mode, i.e. + +::::{tab-set} + +:::{tab-item} TensorFlow {{ tensorflow_icon }} + +```bash +dp train input.json +``` + +::: + +:::{tab-item} PyTorch {{ pytorch_icon }} + +```bash +dp --pt train input.json +``` + +::: + +:::: + +The detailed loss can be found in `lcurve.out`: + +``` +# step rmse_val rmse_trn rmse_lc_val rmse_lc_trn rmse_gl_val rmse_gl_trn lr + 0 8.34e+00 8.26e+00 8.34e+00 8.26e+00 0.00e+00 0.00e+00 1.0e-02 + 100 3.51e-02 8.55e-02 0.00e+00 8.55e-02 4.38e-03 0.00e+00 5.0e-03 + 200 4.77e-02 5.61e-02 0.00e+00 5.61e-02 5.96e-03 0.00e+00 2.5e-03 + 300 5.68e-02 1.47e-02 0.00e+00 0.00e+00 7.10e-03 1.84e-03 1.3e-03 + 400 3.73e-02 3.48e-02 1.99e-02 0.00e+00 2.18e-03 4.35e-03 6.3e-04 + 500 2.77e-02 5.82e-02 1.08e-02 5.82e-02 2.11e-03 0.00e+00 3.2e-04 + 600 2.81e-02 5.43e-02 2.01e-02 0.00e+00 1.01e-03 6.79e-03 1.6e-04 + 700 2.97e-02 3.28e-02 2.03e-02 0.00e+00 1.17e-03 4.10e-03 7.9e-05 + 800 2.25e-02 6.19e-02 9.05e-03 0.00e+00 1.68e-03 7.74e-03 4.0e-05 + 900 3.18e-02 5.54e-02 9.93e-03 5.54e-02 2.74e-03 0.00e+00 2.0e-05 + 1000 2.63e-02 5.02e-02 1.02e-02 5.02e-02 2.01e-03 0.00e+00 1.0e-05 + 1100 3.27e-02 5.89e-02 2.13e-02 5.89e-02 1.43e-03 0.00e+00 5.0e-06 + 1200 2.85e-02 2.42e-02 2.85e-02 0.00e+00 0.00e+00 3.02e-03 2.5e-06 + 1300 3.47e-02 5.71e-02 1.07e-02 5.71e-02 3.00e-03 0.00e+00 1.3e-06 + 1400 3.13e-02 5.76e-02 3.13e-02 5.76e-02 0.00e+00 0.00e+00 6.3e-07 + 1500 3.34e-02 1.11e-02 2.09e-02 0.00e+00 1.57e-03 1.39e-03 3.2e-07 + 1600 3.11e-02 5.64e-02 3.11e-02 5.64e-02 0.00e+00 0.00e+00 1.6e-07 + 1700 2.97e-02 5.05e-02 2.97e-02 5.05e-02 0.00e+00 0.00e+00 7.9e-08 + 1800 2.64e-02 7.70e-02 1.09e-02 0.00e+00 1.94e-03 9.62e-03 4.0e-08 + 1900 3.28e-02 2.56e-02 3.28e-02 0.00e+00 0.00e+00 3.20e-03 2.0e-08 + 2000 2.59e-02 5.71e-02 1.03e-02 5.71e-02 1.94e-03 0.00e+00 1.0e-08 +``` + +One may notice that in each step, some of the local loss and global loss will be `0.0`. This is because our training data and validation data consist of the global system and atomic system, i.e. + +``` + --training_data + >atomic_system + >global_system + --validation_data + >atomic_system + >global_system +``` + +During training, at each step when the `lcurve.out` is printed, the system used for evaluating the training (validation) error may be either with only global or only atomic labels, thus the corresponding atomic or global errors are missing and are printed as zeros. diff --git a/doc/model/train-hybrid.md b/doc/model/train-hybrid.md index c82fe8e961..c0a55d9eb5 100644 --- a/doc/model/train-hybrid.md +++ b/doc/model/train-hybrid.md @@ -1,4 +1,4 @@ -# Descriptor `"hybrid"` {{ tensorflow_icon }} {{ pytorch_icon }} {{ dpmodel_icon }} +# Descriptor `"hybrid"` {{ tensorflow_icon }} {{ pytorch_icon }} {{ dpmodel_icon }} :::{note} **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, DP {{ dpmodel_icon }} @@ -9,6 +9,7 @@ This descriptor hybridizes multiple descriptors to form a new descriptor. For ex ## Theory A hybrid descriptor $\mathcal{D}^i_\text{hyb}$ concatenates multiple kinds of descriptors into one descriptor: + ```math \mathcal{D}^{i}_\text{hyb} = \{ \begin{array}{cccc} @@ -16,14 +17,16 @@ A hybrid descriptor $\mathcal{D}^i_\text{hyb}$ concatenates multiple kinds of de \end{array} \}. ``` + The list of descriptors can be different types or the same descriptors with different parameters. This way, one can set the different cutoff radii for different descriptors.[^1] -[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). +[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). ## Instructions To use the descriptor in DeePMD-kit, one firstly set the {ref}`type ` to {ref}`hybrid `, then provide the definitions of the descriptors by the items in the `list`, + ```json "descriptor" :{ "type": "hybrid", @@ -41,6 +44,7 @@ To use the descriptor in DeePMD-kit, one firstly set the {ref}`type `. An example of the descriptor is provided as follows + ```json "descriptor" :{ "type": "se_a_mask", @@ -39,15 +42,17 @@ The construction of the descriptor is given by section {ref}`descriptor ` of the descriptor is set to `"se_a_mask"`. -* {ref}`sel ` gives the maximum number of atoms in input coordinates. It is a list, the length of which is the same as the number of atom types in the system, and `sel[i]` denotes the maximum number of atoms with type `i`. -* The {ref}`neuron ` specifies the size of the embedding net. From left to right the members denote the sizes of each hidden layer from the input end to the output end, respectively. If the outer layer is twice the size of the inner layer, then the inner layer is copied and concatenated, then a [ResNet architecture](https://arxiv.org/abs/1512.03385) is built between them. -* The {ref}`axis_neuron ` specifies the size of the submatrix of the embedding matrix, the axis matrix as explained in the [DeepPot-SE paper](https://arxiv.org/abs/1805.09003) -* If the option {ref}`type_one_side ` is set to `true`, the embedding network parameters vary by types of neighbor atoms only, so there will be $N_\text{types}$ sets of embedding network parameters. Otherwise, the embedding network parameters vary by types of centric atoms and types of neighbor atoms, so there will be $N_\text{types}^2$ sets of embedding network parameters. -* If the option {ref}`resnet_dt ` is set to `true`, then a timestep is used in the ResNet. -* {ref}`seed ` gives the random seed that is used to generate random numbers when initializing the model parameters. + +- The {ref}`type ` of the descriptor is set to `"se_a_mask"`. +- {ref}`sel ` gives the maximum number of atoms in input coordinates. It is a list, the length of which is the same as the number of atom types in the system, and `sel[i]` denotes the maximum number of atoms with type `i`. +- The {ref}`neuron ` specifies the size of the embedding net. From left to right the members denote the sizes of each hidden layer from the input end to the output end, respectively. If the outer layer is twice the size of the inner layer, then the inner layer is copied and concatenated, then a [ResNet architecture](https://arxiv.org/abs/1512.03385) is built between them. +- The {ref}`axis_neuron ` specifies the size of the submatrix of the embedding matrix, the axis matrix as explained in the [DeepPot-SE paper](https://arxiv.org/abs/1805.09003) +- If the option {ref}`type_one_side ` is set to `true`, the embedding network parameters vary by types of neighbor atoms only, so there will be $N_\text{types}$ sets of embedding network parameters. Otherwise, the embedding network parameters vary by types of centric atoms and types of neighbor atoms, so there will be $N_\text{types}^2$ sets of embedding network parameters. +- If the option {ref}`resnet_dt ` is set to `true`, then a timestep is used in the ResNet. +- {ref}`seed ` gives the random seed that is used to generate random numbers when initializing the model parameters. To make the `aparam.npy` used for descriptor `se_a_mask`, two variables in `fitting_net` section are needed. + ```json "fitting_net" :{ "neuron": [240, 240, 240], @@ -57,14 +62,16 @@ To make the `aparam.npy` used for descriptor `se_a_mask`, two variables in `fitt "use_aparam_as_mask": true } ``` -* `neuron`, `resnet_dt` and `seed` are the same as the {ref}`fitting_net ` section for fitting energy. -* {ref}`numb_aparam ` gives the dimesion of the `aparam.npy` file. In this example, it is set to 1 and stores the real/virtual sign of the atoms. For real/virtual atoms, the corresponding sign in `aparam.npy` is set to 1/0. -* {ref}`use_aparam_as_mask ` is set to `true` to use the `aparam.npy` as the mask of the atoms in the descriptor `se_a_mask`. + +- `neuron`, `resnet_dt` and `seed` are the same as the {ref}`fitting_net ` section for fitting energy. +- {ref}`numb_aparam ` gives the dimesion of the `aparam.npy` file. In this example, it is set to 1 and stores the real/virtual sign of the atoms. For real/virtual atoms, the corresponding sign in `aparam.npy` is set to 1/0. +- {ref}`use_aparam_as_mask ` is set to `true` to use the `aparam.npy` as the mask of the atoms in the descriptor `se_a_mask`. Finally, to make a reasonable fitting task with `se_a_mask` descriptor for DP/MM simulations, the loss function with `se_a_mask` is designed to include the atomic forces difference in specific atoms of the input particles only. More details about the selection of the specific atoms can be found in paper [DP/MM](left to be filled). Thus, `atom_pref.npy` ( [ nframes * natoms ] ) is required as the indicator of the specific atoms in the input particles. And the `loss` section in the training input script should be set as follows. + ```json "loss": { "type": "ener", diff --git a/doc/model/train-se-atten.md b/doc/model/train-se-atten.md index 745c0d1720..364d35805b 100644 --- a/doc/model/train-se-atten.md +++ b/doc/model/train-se-atten.md @@ -19,43 +19,53 @@ Attention-based descriptor $\mathcal{D}^i \in \mathbb{R}^{M \times M_{<}}$, whic ```math \mathcal{D}^i = \frac{1}{N_c^2}(\hat{\mathcal{G}}^i)^T \mathcal{R}^i (\mathcal{R}^i)^T \hat{\mathcal{G}}^i_<, ``` + where $\hat{\mathcal{G}}^i$ represents the embedding matrix $\mathcal{G}^i$ after additional self-attention mechanism and $\mathcal{R}^i$ is defined by the full case in the [`se_e2_a`](./train-se-e2-a.md). Note that we obtain $\mathcal{G}^i$ using the type embedding method by default in this descriptor. To perform the self-attention mechanism, the queries $\mathcal{Q}^{i,l} \in \mathbb{R}^{N_c\times d_k}$, keys $\mathcal{K}^{i,l} \in \mathbb{R}^{N_c\times d_k}$, and values $\mathcal{V}^{i,l} \in \mathbb{R}^{N_c\times d_v}$ are first obtained: + ```math \left(\mathcal{Q}^{i,l}\right)_{j}=Q_{l}\left(\left(\mathcal{G}^{i,l-1}\right)_{j}\right), ``` + ```math \left(\mathcal{K}^{i,l}\right)_{j}=K_{l}\left(\left(\mathcal{G}^{i,l-1}\right)_{j}\right), ``` + ```math \left(\mathcal{V}^{i,l}\right)_{j}=V_{l}\left(\left(\mathcal{G}^{i,l-1}\right)_{j}\right), ``` + where $Q_{l}$, $K_{l}$, $V_{l}$ represent three trainable linear transformations that output the queries and keys of dimension $d_k$ and values of dimension $d_v$, and $l$ is the index of the attention layer. -The input embedding matrix to the attention layers, denoted by $\mathcal{G}^{i,0}$, is chosen as the two-body embedding matrix. +The input embedding matrix to the attention layers, denoted by $\mathcal{G}^{i,0}$, is chosen as the two-body embedding matrix. Then the scaled dot-product attention method is adopted: + ```math A(\mathcal{Q}^{i,l}, \mathcal{K}^{i,l}, \mathcal{V}^{i,l}, \mathcal{R}^{i,l})=\varphi\left(\mathcal{Q}^{i,l}, \mathcal{K}^{i,l},\mathcal{R}^{i,l}\right)\mathcal{V}^{i,l}, ``` + where $\varphi\left(\mathcal{Q}^{i,l}, \mathcal{K}^{i,l},\mathcal{R}^{i,l}\right) \in \mathbb{R}^{N_c\times N_c}$ is attention weights. In the original attention method, one typically has $\varphi\left(\mathcal{Q}^{i,l}, \mathcal{K}^{i,l}\right)=\mathrm{softmax}\left(\frac{\mathcal{Q}^{i,l} (\mathcal{K}^{i,l})^{T}}{\sqrt{d_{k}}}\right)$, with $\sqrt{d_{k}}$ being the normalization temperature. This is slightly modified to incorporate the angular information: + ```math \varphi\left(\mathcal{Q}^{i,l}, \mathcal{K}^{i,l},\mathcal{R}^{i,l}\right) = \mathrm{softmax}\left(\frac{\mathcal{Q}^{i,l} (\mathcal{K}^{i,l})^{T}}{\sqrt{d_{k}}}\right) \odot \hat{\mathcal{R}}^{i}(\hat{\mathcal{R}}^{i})^{T}, ``` + where $\hat{\mathcal{R}}^{i} \in \mathbb{R}^{N_c\times 3}$ denotes normalized relative coordinates , $\hat{\mathcal{R}}^{i}_{j} = \frac{\boldsymbol{r}_{ij}}{\lVert \boldsymbol{r}_{ij} \lVert}$ and $\odot$ means element-wise multiplication. Then layer normalization is added in a residual way to finally obtain the self-attention local embedding matrix $\hat{\mathcal{G}}^{i} = \mathcal{G}^{i,L_a}$ after $L_a$ attention layers:[^1] + ```math \mathcal{G}^{i,l} = \mathcal{G}^{i,l-1} + \mathrm{LayerNorm}(A(\mathcal{Q}^{i,l}, \mathcal{K}^{i,l}, \mathcal{V}^{i,l}, \mathcal{R}^{i,l})). ``` -[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). - +[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). ## Introduction to new features of DPA-1 + Next, we will list the detailed settings in input.json and the data format, especially for large systems with dozens of elements. An example of DPA-1 input can be found [here](../../examples/water/se_atten/input.json). ### Descriptor `"se_atten"` @@ -63,10 +73,12 @@ Next, we will list the detailed settings in input.json and the data format, espe The notation of `se_atten` is short for the smooth edition of Deep Potential with an attention mechanism. This descriptor was described in detail in [the DPA-1 paper](https://arxiv.org/abs/2208.08236) and the images above. -In this example, we will train a DPA-1 model for a water system. A complete training input script of this example can be found in the directory: +In this example, we will train a DPA-1 model for a water system. A complete training input script of this example can be found in the directory: + ```bash $deepmd_source_dir/examples/water/se_atten/input.json ``` + With the training input script, data are also provided in the example directory. One may train the model with the DeePMD-kit from the directory. An example of the DPA-1 descriptor is provided as follows @@ -92,17 +104,17 @@ An example of the DPA-1 descriptor is provided as follows } ``` -* The {ref}`type ` of the descriptor is set to `"se_atten"`, which will use DPA-1 structures. -* {ref}`rcut ` is the cut-off radius for neighbor searching, and the {ref}`rcut_smth ` gives where the smoothing starts. -* **{ref}`sel `** gives the maximum possible number of neighbors in the cut-off radius. It is an int. Note that this number highly affects the efficiency of training, which we usually use less than 200. (We use 120 for training 56 elements in [OC2M dataset](https://github.com/Open-Catalyst-Project/ocp/blob/main/DATASET.md)) -* The {ref}`neuron ` specifies the size of the embedding net. From left to right the members denote the sizes of each hidden layer from the input end to the output end, respectively. If the outer layer is twice the size of the inner layer, then the inner layer is copied and concatenated, then a [ResNet architecture](https://arxiv.org/abs/1512.03385) is built between them. -* The {ref}`axis_neuron ` specifies the size of the submatrix of the embedding matrix, the axis matrix as explained in the [DeepPot-SE paper](https://arxiv.org/abs/1805.09003) -* If the option {ref}`resnet_dt ` is set to `true`, then a timestep is used in the ResNet. -* {ref}`seed ` gives the random seed that is used to generate random numbers when initializing the model parameters. -* {ref}`attn ` sets the length of a hidden vector during scale-dot attention computation. -* {ref}`attn_layer ` sets the number of layers in attention mechanism. -* {ref}`attn_mask ` determines whether to mask the diagonal in the attention weights and False is recommended. -* {ref}`attn_dotr ` determines whether to dot the relative coordinates on the attention weights as a gated scheme, True is recommended. +- The {ref}`type ` of the descriptor is set to `"se_atten"`, which will use DPA-1 structures. +- {ref}`rcut ` is the cut-off radius for neighbor searching, and the {ref}`rcut_smth ` gives where the smoothing starts. +- **{ref}`sel `** gives the maximum possible number of neighbors in the cut-off radius. It is an int. Note that this number highly affects the efficiency of training, which we usually use less than 200. (We use 120 for training 56 elements in [OC2M dataset](https://github.com/Open-Catalyst-Project/ocp/blob/main/DATASET.md)) +- The {ref}`neuron ` specifies the size of the embedding net. From left to right the members denote the sizes of each hidden layer from the input end to the output end, respectively. If the outer layer is twice the size of the inner layer, then the inner layer is copied and concatenated, then a [ResNet architecture](https://arxiv.org/abs/1512.03385) is built between them. +- The {ref}`axis_neuron ` specifies the size of the submatrix of the embedding matrix, the axis matrix as explained in the [DeepPot-SE paper](https://arxiv.org/abs/1805.09003) +- If the option {ref}`resnet_dt ` is set to `true`, then a timestep is used in the ResNet. +- {ref}`seed ` gives the random seed that is used to generate random numbers when initializing the model parameters. +- {ref}`attn ` sets the length of a hidden vector during scale-dot attention computation. +- {ref}`attn_layer ` sets the number of layers in attention mechanism. +- {ref}`attn_mask ` determines whether to mask the diagonal in the attention weights and False is recommended. +- {ref}`attn_dotr ` determines whether to dot the relative coordinates on the attention weights as a gated scheme, True is recommended. ::: @@ -125,37 +137,42 @@ An example of the DPA-1 descriptor is provided as follows } ``` -* The {ref}`type ` of the descriptor is set to `"dpa1"`, which will use DPA-1 structures. -* {ref}`rcut ` is the cut-off radius for neighbor searching, and the {ref}`rcut_smth ` gives where the smoothing starts. -* **{ref}`sel `** gives the maximum possible number of neighbors in the cut-off radius. It is an int. Note that this number highly affects the efficiency of training, which we usually use less than 200. (We use 120 for training 56 elements in [OC2M dataset](https://github.com/Open-Catalyst-Project/ocp/blob/main/DATASET.md)) -* The {ref}`neuron ` specifies the size of the embedding net. From left to right the members denote the sizes of each hidden layer from the input end to the output end, respectively. If the outer layer is twice the size of the inner layer, then the inner layer is copied and concatenated, then a [ResNet architecture](https://arxiv.org/abs/1512.03385) is built between them. -* The {ref}`tebd_dim ` specifies the dimension of the type embedding. -* The {ref}`axis_neuron ` specifies the size of the submatrix of the embedding matrix, the axis matrix as explained in the [DeepPot-SE paper](https://arxiv.org/abs/1805.09003) -* {ref}`attn ` sets the length of a hidden vector during scale-dot attention computation. -* {ref}`attn_layer ` sets the number of layers in attention mechanism. -* {ref}`attn_mask ` determines whether to mask the diagonal in the attention weights and False is recommended. -* {ref}`attn_dotr ` determines whether to dot the relative coordinates on the attention weights as a gated scheme, True is recommended. -* {ref}`post_ln ` determines whether to perform post layer norm. +- The {ref}`type ` of the descriptor is set to `"dpa1"`, which will use DPA-1 structures. +- {ref}`rcut ` is the cut-off radius for neighbor searching, and the {ref}`rcut_smth ` gives where the smoothing starts. +- **{ref}`sel `** gives the maximum possible number of neighbors in the cut-off radius. It is an int. Note that this number highly affects the efficiency of training, which we usually use less than 200. (We use 120 for training 56 elements in [OC2M dataset](https://github.com/Open-Catalyst-Project/ocp/blob/main/DATASET.md)) +- The {ref}`neuron ` specifies the size of the embedding net. From left to right the members denote the sizes of each hidden layer from the input end to the output end, respectively. If the outer layer is twice the size of the inner layer, then the inner layer is copied and concatenated, then a [ResNet architecture](https://arxiv.org/abs/1512.03385) is built between them. +- The {ref}`tebd_dim ` specifies the dimension of the type embedding. +- The {ref}`axis_neuron ` specifies the size of the submatrix of the embedding matrix, the axis matrix as explained in the [DeepPot-SE paper](https://arxiv.org/abs/1805.09003) +- {ref}`attn ` sets the length of a hidden vector during scale-dot attention computation. +- {ref}`attn_layer ` sets the number of layers in attention mechanism. +- {ref}`attn_mask ` determines whether to mask the diagonal in the attention weights and False is recommended. +- {ref}`attn_dotr ` determines whether to dot the relative coordinates on the attention weights as a gated scheme, True is recommended. +- {ref}`post_ln ` determines whether to perform post layer norm. ::: :::: ### Descriptor `"se_atten_v2"` + We highly recommend using the version 2.0 of the attention-based descriptor `"se_atten_v2"`, which is inherited from `"se_atten"` but with the following parameter modifications: + ```json "stripped_type_embedding": true, "smooth_type_embdding": true, "set_davg_zero": false ``` -Practical evidence demonstrates that `"se_atten_v2"` offers better and more stable performance compared to `"se_atten"`. +Practical evidence demonstrates that `"se_atten_v2"` offers better and more stable performance compared to `"se_atten"`. ### Fitting `"ener"` + DPA-1 only supports `"ener"` fitting type, and you can refer [here](train-energy.md) for detailed information. ### Type embedding + DPA-1 only supports models with type embeddings. And the default setting is as follows: + ```json "type_embedding":{ "neuron": [8], @@ -163,11 +180,13 @@ DPA-1 only supports models with type embeddings. And the default setting is as f "seed": 1 } ``` -You can add these settings in input.json if you want to change the default ones, see [here](train-se-e2-a-tebd.md) for detailed information. +You can add these settings in input.json if you want to change the default ones, see [here](train-se-e2-a-tebd.md) for detailed information. ### Type map + For training large systems, especially those with dozens of elements, the {ref}`type ` determines the element index of training data: + ```json "type_map": [ "Mg", @@ -175,8 +194,11 @@ For training large systems, especially those with dozens of elements, the {ref}` "Cu" ] ``` + which should include all the elements in the dataset you want to train on. + ## Data format + DPA-1 supports the standard data format, which is detailed in [data-conv.md](../data/data-conv.md) and [system.md](../data/system.md). Note that in this format, only those frames with the same fingerprint (i.e. the number of atoms of different elements) can be put together as a unified system. This may lead to sparse frame numbers in those rare systems. @@ -184,6 +206,7 @@ This may lead to sparse frame numbers in those rare systems. An ideal way is to put systems with the same total number of atoms together, which is the way we trained DPA-1 on [OC2M](https://github.com/Open-Catalyst-Project/ocp/blob/main/DATASET.md). This system format, which is called `mixed_type`, is proper to put frame-sparse systems together and is slightly different from the standard one. Take an example, a `mixed_type` may contain the following files: + ``` type.raw type_map.raw @@ -193,13 +216,14 @@ set.*/energy.npy set.*/force.npy set.*/real_atom_types.npy ``` + This system contains `Nframes` frames with the same atom number `Natoms`, the total number of element types contained in all frames is `Ntypes`. Most files are the same as those in [standard formats](../data/system.md), here we only list the distinct ones: -ID | Property | File | Required/Optional | Shape | Description ----------- | -------------------------------- | ------------------- | -------------------- | ----------------------- | ----------- -/ | Atom type indexes (place holder) | type.raw | Required | Natoms | All zeros to fake the type input -type_map | Atom type names | type_map.raw | Required | Ntypes | Atom names that map to atom type contained in all the frames, which is unnecessart to be contained in the periodic table -type | Atom type indexes of each frame | real_atom_types.npy | Required | Nframes \* Natoms | Integers that describe atom types in each frame, corresponding to indexes in type_map. `-1` means virtual atoms. +| ID | Property | File | Required/Optional | Shape | Description | +| -------- | -------------------------------- | ------------------- | ----------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------ | +| / | Atom type indexes (place holder) | type.raw | Required | Natoms | All zeros to fake the type input | +| type_map | Atom type names | type_map.raw | Required | Ntypes | Atom names that map to atom type contained in all the frames, which is unnecessart to be contained in the periodic table | +| type | Atom type indexes of each frame | real_atom_types.npy | Required | Nframes \* Natoms | Integers that describe atom types in each frame, corresponding to indexes in type_map. `-1` means virtual atoms. | With these edited files, one can put together frames with the same `Natoms`, instead of the same formula (like `H2O`). Note that this `mixed_type` format only supports `se_atten` descriptor. @@ -208,6 +232,7 @@ To put frames with different `Natoms` into the same system, one can pad systems The API to generate or transfer to `mixed_type` format is available on [dpdata](https://github.com/deepmodeling/dpdata) for a more convenient experience. ## Training example + Here we upload the AlMgCu example shown in the paper, you can download it here: [Baidu disk](https://pan.baidu.com/s/1Mk9CihPHCmf8quwaMhT-nA?pwd=d586); [Google disk](https://drive.google.com/file/d/11baEpRrvHoqxORFPSdJiGWusb3Y4AnRE/view?usp=sharing). diff --git a/doc/model/train-se-e2-a-tebd.md b/doc/model/train-se-e2-a-tebd.md index 7797a8f3c0..a6291bb238 100644 --- a/doc/model/train-se-e2-a-tebd.md +++ b/doc/model/train-se-e2-a-tebd.md @@ -16,6 +16,7 @@ Usually, when the type embedding approach is not enabled, for a system with mult (\mathcal{G}^i)_j = \mathcal{N}^{\alpha_i, \alpha_j}_{e,2}(s(r_{ij})) \quad \mathrm{or}\quad (\mathcal{G}^i)_j = \mathcal{N}^{ \alpha_j}_{e,2}(s(r_{ij})), ``` + ```math (\mathcal{G}^i)_{jk} =\mathcal{N}^{\alpha_j, \alpha_k}_{e,3}((\theta_i)_{jk}). ``` @@ -28,6 +29,7 @@ The limitation of this approach is that when there are large numbers of chemical Similar to the embedding networks, if the type embedding approach is not used, the fitting network parameters are chemical-species-wise, and there are $N_t$ sets of fitting network parameters. For performance, atoms are sorted by their chemical species $\alpha_i$ in advance. Take an example, the atomic energy $E_i$ is represented as follows: + ```math E_i=\mathcal{F}_0^{\alpha_i}(\mathcal{D}^i). ``` @@ -46,21 +48,25 @@ The type embeddings of central and neighboring atoms $\mathcal{A}^i$ and $\mathc (\mathcal{G}^i)_j = \mathcal{N}_{e,2}(\{s(r_{ij}), \mathcal{A}^i, \mathcal{A}^j\}) \quad \mathrm{or}\quad (\mathcal{G}^i)_j = \mathcal{N}_{e,2}(\{s(r_{ij}), \mathcal{A}^j\}) , ``` + ```math (\mathcal{G}^i)_{jk} =\mathcal{N}_{e,3}(\{(\theta_i)_{jk}, \mathcal{A}^j, \mathcal{A}^k\}). ``` In fitting networks, the type embedding is inserted into the input of the fitting networks: + ```math E_i=\mathcal{F}_0(\{\mathcal{D}^i, \mathcal{A}^i\}). ``` In this way, all chemical species share the same network parameters through the type embedding.[^1] -[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). +[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). ## Instructions + The {ref}`model ` defines how the model is constructed, adding a section of type embedding net: + ```json "model": { "type_map": ["O", "H"], @@ -75,9 +81,11 @@ The {ref}`model ` defines how the model is constructed, adding a section } } ``` + The model will automatically apply the type embedding approach and generate type embedding vectors. If the type embedding vector is detected, the descriptor and fitting net would take it as a part of the input. The construction of type embedding net is given by {ref}`type_embedding `. An example of {ref}`type_embedding ` is provided as follows + ```json "type_embedding":{ "neuron": [2, 4, 8], @@ -85,15 +93,17 @@ The construction of type embedding net is given by {ref}`type_embedding ` specifies the size of the type embedding net. From left to right the members denote the sizes of each hidden layer from the input end to the output end, respectively. It takes a one-hot vector as input and output dimension equals to the last dimension of the {ref}`neuron ` list. If the outer layer is twice the size of the inner layer, then the inner layer is copied and concatenated, then a [ResNet architecture](https://arxiv.org/abs/1512.03385) is built between them. -* If the option {ref}`resnet_dt ` is set to `true`, then a timestep is used in the ResNet. -* {ref}`seed ` gives the random seed that is used to generate random numbers when initializing the model parameters. +- The {ref}`neuron ` specifies the size of the type embedding net. From left to right the members denote the sizes of each hidden layer from the input end to the output end, respectively. It takes a one-hot vector as input and output dimension equals to the last dimension of the {ref}`neuron ` list. If the outer layer is twice the size of the inner layer, then the inner layer is copied and concatenated, then a [ResNet architecture](https://arxiv.org/abs/1512.03385) is built between them. +- If the option {ref}`resnet_dt ` is set to `true`, then a timestep is used in the ResNet. +- {ref}`seed ` gives the random seed that is used to generate random numbers when initializing the model parameters. A complete training input script of this example can be found in the directory. + ```bash $deepmd_source_dir/examples/water/se_e2_a_tebd/input.json ``` + See [here](../development/type-embedding.md) for further explanation of `type embedding`. :::{note} diff --git a/doc/model/train-se-e2-a.md b/doc/model/train-se-e2-a.md index e99f14518e..2412bbc64e 100644 --- a/doc/model/train-se-e2-a.md +++ b/doc/model/train-se-e2-a.md @@ -43,10 +43,10 @@ where $\boldsymbol{r}_{ij}=\boldsymbol{r}_j-\boldsymbol{r}_i = (x_{ij}, y_{ij}, \end{cases} ``` -where $x=\frac{r - r_s}{ r_c - r_s}$ switches from 1 at $r_s$ to 0 at the cutoff radius $r_c$. +where $x=\frac{r - r_s}{ r_c - r_s}$ switches from 1 at $r_s$ to 0 at the cutoff radius $r_c$. The switching function $s(r)$ is smooth in the sense that the second-order derivative is continuous. -Each row of the embedding matrix $\mathcal{G}^i \in \mathbb{R}^{N_c \times M}$ consists of $M$ nodes from the output layer of an NN function $\mathcal{N}_ {g}$ of $s(r_{ij})$: +Each row of the embedding matrix $\mathcal{G}^i \in \mathbb{R}^{N_c \times M}$ consists of $M$ nodes from the output layer of an NN function $\mathcal{N}_ {g}$ of $s(r_{ij})$: ```math (\mathcal{G}^i)_j = \mathcal{N}_{e,2}(s(r_{ij})), @@ -58,17 +58,20 @@ $\mathcal{G}^i_< \in \mathbb{R}^{N_c \times M_<}$ only takes first $M_<$ columns $r_s$, $r_c$, $M$ and $M_<$ are hyperparameters provided by the user. The DeepPot-SE is continuous up to the second-order derivative in its domain.[^1] -[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). +[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). ## Instructions -In this example, we will train a DeepPot-SE model for a water system. A complete training input script of this example can be found in the directory. +In this example, we will train a DeepPot-SE model for a water system. A complete training input script of this example can be found in the directory. + ```bash $deepmd_source_dir/examples/water/se_e2_a/input.json ``` + With the training input script, data are also provided in the example directory. One may train the model with the DeePMD-kit from the directory. The construction of the descriptor is given by section {ref}`descriptor `. An example of the descriptor is provided as follows + ```json "descriptor" :{ "type": "se_e2_a", @@ -82,11 +85,12 @@ The construction of the descriptor is given by section {ref}`descriptor ` of the descriptor is set to `"se_e2_a"`. -* {ref}`rcut ` is the cut-off radius for neighbor searching, and the {ref}`rcut_smth ` gives where the smoothing starts. -* {ref}`sel ` gives the maximum possible number of neighbors in the cut-off radius. It is a list, the length of which is the same as the number of atom types in the system, and `sel[i]` denotes the maximum possible number of neighbors with type `i`. -* The {ref}`neuron ` specifies the size of the embedding net. From left to right the members denote the sizes of each hidden layer from the input end to the output end, respectively. If the outer layer is twice the size of the inner layer, then the inner layer is copied and concatenated, then a [ResNet architecture](https://arxiv.org/abs/1512.03385) is built between them. -* If the option {ref}`type_one_side ` is set to `true`, the embedding network parameters vary by types of neighbor atoms only, so there will be $N_\text{types}$ sets of embedding network parameters. Otherwise, the embedding network parameters vary by types of centric atoms and types of neighbor atoms, so there will be $N_\text{types}^2$ sets of embedding network parameters. -* The {ref}`axis_neuron ` specifies the size of the submatrix of the embedding matrix, the axis matrix as explained in the [DeepPot-SE paper](https://arxiv.org/abs/1805.09003) -* If the option {ref}`resnet_dt ` is set to `true`, then a timestep is used in the ResNet. -* {ref}`seed ` gives the random seed that is used to generate random numbers when initializing the model parameters. + +- The {ref}`type ` of the descriptor is set to `"se_e2_a"`. +- {ref}`rcut ` is the cut-off radius for neighbor searching, and the {ref}`rcut_smth ` gives where the smoothing starts. +- {ref}`sel ` gives the maximum possible number of neighbors in the cut-off radius. It is a list, the length of which is the same as the number of atom types in the system, and `sel[i]` denotes the maximum possible number of neighbors with type `i`. +- The {ref}`neuron ` specifies the size of the embedding net. From left to right the members denote the sizes of each hidden layer from the input end to the output end, respectively. If the outer layer is twice the size of the inner layer, then the inner layer is copied and concatenated, then a [ResNet architecture](https://arxiv.org/abs/1512.03385) is built between them. +- If the option {ref}`type_one_side ` is set to `true`, the embedding network parameters vary by types of neighbor atoms only, so there will be $N_\text{types}$ sets of embedding network parameters. Otherwise, the embedding network parameters vary by types of centric atoms and types of neighbor atoms, so there will be $N_\text{types}^2$ sets of embedding network parameters. +- The {ref}`axis_neuron ` specifies the size of the submatrix of the embedding matrix, the axis matrix as explained in the [DeepPot-SE paper](https://arxiv.org/abs/1805.09003) +- If the option {ref}`resnet_dt ` is set to `true`, then a timestep is used in the ResNet. +- {ref}`seed ` gives the random seed that is used to generate random numbers when initializing the model parameters. diff --git a/doc/model/train-se-e2-r.md b/doc/model/train-se-e2-r.md index c543df6b22..f427310196 100644 --- a/doc/model/train-se-e2-r.md +++ b/doc/model/train-se-e2-r.md @@ -18,7 +18,7 @@ where $N_c$ is the expected maximum number of neighboring atoms, which is the same constant for all atoms over all frames. A matrix with a dimension of $N_c$ will be padded if the number of neighboring atoms is less than $N_c$. -Each row of the embedding matrix $\mathcal{G}^i \in \mathbb{R}^{N_c \times M}$ consists of $M$ nodes from the output layer of an NN function $\mathcal{N}_ {g}$ of $s(r_{ij})$: +Each row of the embedding matrix $\mathcal{G}^i \in \mathbb{R}^{N_c \times M}$ consists of $M$ nodes from the output layer of an NN function $\mathcal{N}_ {g}$ of $s(r_{ij})$: ```math (\mathcal{G}^i)_j = \mathcal{N}_{e,2}(s(r_{ij})), @@ -35,23 +35,25 @@ where $\boldsymbol{r}_ {ij}=\boldsymbol{r}_ j-\boldsymbol{r}_ i = (x_{ij}, y_{ij \end{cases} ``` -where $x=\frac{r - r_s}{ r_c - r_s}$ switches from 1 at $r_s$ to 0 at the cutoff radius $r_c$. +where $x=\frac{r - r_s}{ r_c - r_s}$ switches from 1 at $r_s$ to 0 at the cutoff radius $r_c$. The switching function $s(r)$ is smooth in the sense that the second-order derivative is continuous. In the above equations, the network parameters are not explicitly written. $r_s$, $r_c$ and $M$ are hyperparameters provided by the user. The DeepPot-SE is continuous up to the second-order derivative in its domain.[^1] -[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). +[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). ## Instructions A complete training input script of this example can be found in the directory + ```bash $deepmd_source_dir/examples/water/se_e2_r/input.json ``` The training input script is very similar to that of [`se_e2_a`](train-se-e2-a.md). The only difference lies in the {ref}`descriptor ` section + ```json "descriptor": { "type": "se_e2_r", @@ -65,4 +67,5 @@ The training input script is very similar to that of [`se_e2_a`](train-se-e2-a.m "_comment": " that's all" }, ``` + The type of the descriptor is set by the key {ref}`type `. diff --git a/doc/model/train-se-e3.md b/doc/model/train-se-e3.md index 4eb35357a0..3a0c1a9547 100644 --- a/doc/model/train-se-e3.md +++ b/doc/model/train-se-e3.md @@ -9,9 +9,11 @@ The notation of `se_e3` is short for the Deep Potential Smooth Edition (DeepPot- ## Theory The three-body embedding DeepPot-SE descriptor incorporates bond-angle information, making the model more accurate. The descriptor $\mathcal{D}^i$ can be represented as + ```math \mathcal{D}^i = \frac{1}{N_c^2}(\mathcal{R}^i(\mathcal{R}^i)^T):\mathcal{G}^i, ``` + where $N_c$ is the expected maximum number of neighboring atoms, which is the same constant for all atoms over all frames. $\mathcal{R}^i$ is constructed as @@ -24,6 +26,7 @@ $\mathcal{R}^i$ is constructed as \end{array} \}, ``` + Currently, only the full information case of $\mathcal{R}^i$ is supported by the three-body embedding. Each element of $\mathcal{G}^i \in \mathbb{R}^{N_c \times N_c \times M}$ comes from $M$ nodes from the output layer of an NN $\mathcal{N}_{e,3}$ function: @@ -34,16 +37,18 @@ Each element of $\mathcal{G}^i \in \mathbb{R}^{N_c \times N_c \times M}$ comes f where $(\theta_i)_ {jk} = (\mathcal{R}^i)_ {j,\\{2,3,4\\}}\cdot (\mathcal{R}^i)_ {k,\\{2,3,4\\}}$ considers the angle form of two neighbours ($j$ and $k$). The notation $:$ in the equation indicates the contraction between matrix $\mathcal{R}^i(\mathcal{R}^i)^T$ and the first two dimensions of tensor $\mathcal{G}^i$.[^1] -[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). +[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). ## Instructions A complete training input script of this example can be found in the directory + ```bash $deepmd_source_dir/examples/water/se_e3/input.json ``` The training input script is very similar to that of [`se_e2_a`](train-se-e2-a.md). The only difference lies in the `descriptor ` section + ```json "descriptor": { "type": "se_e3", @@ -56,4 +61,5 @@ The training input script is very similar to that of [`se_e2_a`](train-se-e2-a.m "_comment": " that's all" }, ``` + The type of the descriptor is set by the key {ref}`type `. diff --git a/doc/nvnmd/nvnmd.md b/doc/nvnmd/nvnmd.md index 7c00baad27..67cfb5e22d 100644 --- a/doc/nvnmd/nvnmd.md +++ b/doc/nvnmd/nvnmd.md @@ -33,7 +33,6 @@ where `$dataset` is the path to the data set and `$workspace` is the path to the Create and go to the training directory. - ```bash mkdir train cd train @@ -50,10 +49,10 @@ The structure of the input script is as follows ```json { - "nvnmd" : {}, - "learning_rate" : {}, - "loss" : {}, - "training": {} + "nvnmd": {}, + "learning_rate": {}, + "loss": {}, + "training": {} } ``` @@ -63,29 +62,30 @@ The "nvnmd" section is defined as ```json { - "version": 0, - "max_nnei":128, - "net_size":128, - "sel":[60, 60], - "rcut":6.0, - "rcut_smth":0.5, - "type_map": ["Ge", "Te"] + "version": 0, + "max_nnei": 128, + "net_size": 128, + "sel": [60, 60], + "rcut": 6.0, + "rcut_smth": 0.5, + "type_map": ["Ge", "Te"] } ``` where items are defined as: -| Item | Mean | Optional Value | -| --------- | --------------------------- | --------------------------------------------- | -| version | the version of network structure | 0 or 1 | -| max_nnei | the maximum number of neighbors that do not distinguish element types | 128 or 256 | -| net_size | the size of nueral network | 128 | -| sel | the number of neighbors | version 0: integer list of lengths 1 to 4 are acceptable; version 1: integer | -| rcut | the cutoff radial | (0, 8.0] | -| rcut_smth | the smooth cutoff parameter | (0, 8.0] | -| type_map | mapping atom type to the name (str) of the type | string list, optional | +| Item | Mean | Optional Value | +| --------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| version | the version of network structure | 0 or 1 | +| max_nnei | the maximum number of neighbors that do not distinguish element types | 128 or 256 | +| net_size | the size of nueral network | 128 | +| sel | the number of neighbors | version 0: integer list of lengths 1 to 4 are acceptable; version 1: integer | +| rcut | the cutoff radial | (0, 8.0] | +| rcut_smth | the smooth cutoff parameter | (0, 8.0] | +| type_map | mapping atom type to the name (str) of the type | string list, optional | Multiple versions of the nvnmd model correspond to different network structures. `nvnmd-v0` and `nvnmd-v1` differ in the following ways: + 1. `nvnmd-v0` and `nvnmd-v1` use the `se_a` descriptor and `se_atten` descriptor, respectively 2. `nvnmd-v0` has 1 set of parameters for each element and supports up to 4 element types. `nvnmd-v1` shares 1 set of parameters for each element and supports up to 31 types. 3. `nvnmd-v0` distinguishes between neighboring atoms, so `sel` is a list of integers. `nvnmd-v1` does not distinguish between neighboring atoms, so `sel` is an integer. @@ -96,20 +96,20 @@ The "learning_rate" section is defined as ```json { - "type":"exp", - "start_lr": 1e-3, - "stop_lr": 3e-8, - "decay_steps": 5000 + "type": "exp", + "start_lr": 1e-3, + "stop_lr": 3e-8, + "decay_steps": 5000 } ``` where items are defined as: -| Item | Mean | Optional Value | -| ----------- | ------------------------------------------------------------ | ---------------------- | -| type | learning rate variant type | exp | -| start_lr | the learning rate at the beginning of the training | a positive real number | -| stop_lr | the desired learning rate at the end of the training | a positive real number | +| Item | Mean | Optional Value | +| ----------- | ---------------------------------------------------------------- | ---------------------- | +| type | learning rate variant type | exp | +| start_lr | the learning rate at the beginning of the training | a positive real number | +| stop_lr | the desired learning rate at the end of the training | a positive real number | | decay_stops | the learning rate is decaying every {decay_stops} training steps | a positive integer | ### loss @@ -118,12 +118,12 @@ The "loss" section is defined as ```json { - "start_pref_e": 0.02, - "limit_pref_e": 2, - "start_pref_f": 1000, - "limit_pref_f": 1, - "start_pref_v": 0, - "limit_pref_v": 0 + "start_pref_e": 0.02, + "limit_pref_e": 2, + "start_pref_f": 1000, + "limit_pref_f": 1, + "start_pref_v": 0, + "limit_pref_v": 0 } ``` @@ -145,17 +145,17 @@ The "training" section is defined as ```json { "seed": 1, - "stop_batch": 1000000, - "numb_test": 1, - "disp_file": "lcurve.out", - "disp_freq": 1000, - "save_ckpt": "model.ckpt", - "save_freq": 10000, - "training_data":{ - "systems":["system1_path", "system2_path", "..."], - "set_prefix": "set", - "batch_size": ["batch_size_of_system1", "batch_size_of_system2", "..."] - } + "stop_batch": 1000000, + "numb_test": 1, + "disp_file": "lcurve.out", + "disp_freq": 1000, + "save_ckpt": "model.ckpt", + "save_freq": 10000, + "training_data": { + "systems": ["system1_path", "system2_path", "..."], + "set_prefix": "set", + "batch_size": ["batch_size_of_system1", "batch_size_of_system2", "..."] + } } ``` @@ -189,20 +189,19 @@ After the training process, you will get two folders: `nvnmd_cnn` and `nvnmd_qnn You can also restart the CNN training from the path prefix of checkpoint files (`nvnmd_cnn/model.ckpt`) by -``` bash +```bash dp train-nvnmd train_cnn.json -r nvnmd_cnn/model.ckpt -s s1 ``` You can also initialize the CNN model and train it by -``` bash +```bash mv nvnmd_cnn nvnmd_cnn_bck cp train_cnn.json train_cnn2.json # please edit train_cnn2.json dp train-nvnmd train_cnn2.json -s s1 -i nvnmd_cnn_bck/model.ckpt ``` - # Testing The frozen model can be used in many ways. The most straightforward testing can be invoked by @@ -215,6 +214,7 @@ dp test -m ./nvnmd_qnn/frozen_model.pb -s path/to/system -d ./test/detail -n 999 where the frozen model file to import is given via the `-m` command line flag, the path to the testing data set is given via the `-s` command line flag, and the file containing details of energy, forces and virials accuracy is given via the `-d` command line flag, the amount of data for testing is given via the `-n` command line flag. # Running MD in Bohrium + After CNN and QNN training, you can upload the ML model to our online NVNMD system and run MD there through Bohrium (https://bohrium.dp.tech). Bohrium is a research platfrom designed for AI for Science Era. For more information, please refer to [Bohrium Introduction](https://bohrium-doc.dp.tech/en/docs/WhatIsBohrium/). ## Registration @@ -251,30 +251,30 @@ Then you need prepare the configuration file `job.json`, the configuration file ```json { - "job_name": "test", - "command": "/usr/bin/lmp_mpi < in.lmp;", - "log_file": "OUTCAR", - "machine_type": "c4_m16_cpu", - "job_type": "container", - "image_name": "lammps_dp:29Sep2021", - "platform": "hnugba", - "region": "default", - "project_id": 0000 + "job_name": "test", + "command": "/usr/bin/lmp_mpi < in.lmp;", + "log_file": "OUTCAR", + "machine_type": "c4_m16_cpu", + "job_type": "container", + "image_name": "lammps_dp:29Sep2021", + "platform": "hnugba", + "region": "default", + "project_id": 0000 } ``` where items are defined as: -| Item | Mean | Optional Value | -| ------------ | -------------------------------------------------------------------------------------------------------------------------- | -------------- | -| job_name | the name of computing job, which can be named freely | a string | -| command | the command to be executed on the computing node | a string | -| log_file | the log file that can be viewed at any time during the calculation process, which can be viewed on the Bohrium "Jobs" page | a string | -| machine_type | the machine type used for the job | "c1_m4_cpu", "c4_m16_cpu", "c8_m32_cpu" | -| job_type | the job type | "container" | -| image_name | the image name used for the job | "lammps_dp:29Sep2021"| -| platform | resource provider | "hnugba" | -| project_id | the project ID to which the job belongs, which can be viewed on the "Projects" page | a integer | +| Item | Mean | Optional Value | +| ------------ | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | +| job_name | the name of computing job, which can be named freely | a string | +| command | the command to be executed on the computing node | a string | +| log_file | the log file that can be viewed at any time during the calculation process, which can be viewed on the Bohrium "Jobs" page | a string | +| machine_type | the machine type used for the job | "c1_m4_cpu", "c4_m16_cpu", "c8_m32_cpu" | +| job_type | the job type | "container" | +| image_name | the image name used for the job | "lammps_dp:29Sep2021" | +| platform | resource provider | "hnugba" | +| project_id | the project ID to which the job belongs, which can be viewed on the "Projects" page | a integer | Notice：The task will use 4 CPU cores for computation, so do not repeatedly use the `mpirun` command, otherwise an error will be reported. All 0000 after "project_id" need to be replaced with your own project ID, which can be viewed on the "Projects" page. Also, the JSON file format requires that no commas be added after the last field within the {}, otherwise, there will be a syntax error. Please check the [documentation](https://github.com/LiuGroupHNU/md-data/blob/master/code/doc/mdpu/hardware.md) for the latest hardware configuration information. diff --git a/doc/test/model-deviation.md b/doc/test/model-deviation.md index a59696c5ee..441d1aabc6 100644 --- a/doc/test/model-deviation.md +++ b/doc/test/model-deviation.md @@ -6,50 +6,61 @@ Model deviation $\epsilon_y$ is the standard deviation of properties $\boldsymbo The DeePMD-kit supports $\boldsymbol y$ to be the atomic force $\boldsymbol F_i$ and the virial tensor $\boldsymbol \Xi$. The model deviation is used to estimate the error of a model at a certain data frame, denoted by $\boldsymbol x$, containing the coordinates and chemical species of all atoms. We present the model deviation of the atomic force and the virial tensor + ```math \epsilon_{\boldsymbol{F},i} (\boldsymbol x)= \sqrt{\langle \lVert \boldsymbol F_i(\boldsymbol x; \boldsymbol \theta_k)-\langle \boldsymbol F_i(\boldsymbol x; \boldsymbol \theta_k) \rangle \rVert^2 \rangle}, ``` + ```math \epsilon_{\boldsymbol{\Xi},{\alpha \beta}} (\boldsymbol x)= \frac{1}{N} \sqrt{\langle ( {\Xi}_{\alpha \beta}(\boldsymbol x; \boldsymbol \theta_k)-\langle {\Xi}_{\alpha \beta}(\boldsymbol x; \boldsymbol \theta_k) \rangle )^2 \rangle}, ``` + where $\boldsymbol \theta_k$ is the parameters of the model $\mathcal M_k$, and the ensemble average $\langle\cdot\rangle$ is estimated by + ```math \langle \boldsymbol y(\boldsymbol x; \boldsymbol \theta_k) \rangle = \frac{1}{n_m} \sum_{k=1}^{n_m} \boldsymbol y(\boldsymbol x; \boldsymbol \theta_k). ``` + Small $\epsilon_{\boldsymbol{F},i}$ means the model has learned the given data; otherwise, it is not covered, and the training data needs to be expanded. If the magnitude of $\boldsymbol F_i$ or $\boldsymbol \Xi$ is quite large, a relative model deviation $\epsilon_{\boldsymbol{F},i,\text{rel}}$ or $\epsilon_{\boldsymbol{\Xi},\alpha\beta,\text{rel}}$ can be used instead of the absolute model deviation: + ```math \epsilon_{\boldsymbol{F},i,\text{rel}} (\boldsymbol x) = \frac{\lvert \epsilon_{\boldsymbol{F},i} (\boldsymbol x) \lvert} {\lvert \langle \boldsymbol F_i (\boldsymbol x; \boldsymbol \theta_k) \rangle \lvert + \nu}, ``` + ```math \epsilon_{\boldsymbol{\Xi},\alpha\beta,\text{rel}} (\boldsymbol x) = \frac{ \epsilon_{\boldsymbol{\Xi},\alpha\beta} (\boldsymbol x) } {\lvert \langle \boldsymbol \Xi (\boldsymbol x; \boldsymbol \theta_k) \rangle \lvert + \nu}, ``` + where $\nu$ is a small constant used to protect an atom where the magnitude of $\boldsymbol{F}_i$ or $\boldsymbol{\Xi}$ is small from having a large model deviation. Statistics of $\epsilon_{\boldsymbol{F},i}$ and $\epsilon_{\boldsymbol{\Xi},{\alpha \beta}}$ can be provided, including the maximum, average, and minimal model deviation over the atom index $i$ and over the component index $\alpha,\beta$, respectively. The maximum model deviation of forces $\epsilon_{\boldsymbol F,\text{max}}$ in a frame was found to be the best error indicator in a concurrent or active learning algorithm.[^1] -[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). +[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). ## Instructions One can also use a subcommand to calculate the deviation of predicted forces or virials for a bunch of models in the following way: + ```bash dp model-devi -m graph.000.pb graph.001.pb graph.002.pb graph.003.pb -s ./data -o model_devi.out ``` + where `-m` specifies graph files to be calculated, `-s` gives the data to be evaluated, `-o` the file to which model deviation results is dumped. Here is more information on this sub-command: + ```bash usage: dp model-devi [-h] [-v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [-l LOG_PATH] [-m MODELS [MODELS ...]] [-s SYSTEM] diff --git a/doc/test/test.md b/doc/test/test.md index c206e8d777..251a12c7e2 100644 --- a/doc/test/test.md +++ b/doc/test/test.md @@ -1,14 +1,19 @@ # Test a model The frozen model can be used in many ways. The most straightforward test can be performed using `dp test`. A typical usage of `dp test` is + ```bash dp test -m graph.pb -s /path/to/system -n 30 ``` + where `-m` gives the tested model, `-s` the path to the tested system and `-n` the number of tested frames. Several other command line options can be passed to `dp test`, which can be checked with + ```bash $ dp test --help ``` + An explanation will be provided + ``` usage: dp test [-h] [-m MODEL] [-s SYSTEM] [-S SET_PREFIX] [-n NUMB_TEST] [-r RAND_SEED] [--shuffle-test] [-d DETAIL_FILE] diff --git a/doc/third-party/ase.md b/doc/third-party/ase.md index ac65fc926e..76371a3197 100644 --- a/doc/third-party/ase.md +++ b/doc/third-party/ase.md @@ -1,6 +1,7 @@ # Use deep potential with ASE Deep potential can be set up as a calculator with ASE to obtain potential energies and forces. + ```python from ase import Atoms from deepmd.calculator import DP @@ -16,6 +17,7 @@ print(water.get_forces()) ``` Optimization is also available: + ```python from ase.optimize import BFGS diff --git a/doc/third-party/gromacs.md b/doc/third-party/gromacs.md index 672fb693b9..c9779611e7 100644 --- a/doc/third-party/gromacs.md +++ b/doc/third-party/gromacs.md @@ -1,10 +1,15 @@ # Running MD with GROMACS + ## DP/MM Simulation + This part gives a simple tutorial on how to run a DP/MM simulation for methane in water, which means using DP for methane and TIP3P for water. All relevant files can be found in `examples/methane`. + ### Topology Preparation + Similar to QM/MM simulation, the internal interactions (including bond, angle, dihedrals, LJ, Columb) of the region described by a neural network potential (NNP) have to be **turned off**. In GROMACS, bonded interactions can be turned off by modifying `[ bonds ]`, `[ angles ]`, `[ dihedrals ]` and `[ pairs ]` sections. And LJ and Columb interactions must be turned off by `[ exclusions ]` section. For example, if one wants to simulate ethane in water, using DeepPotential for methane and TIP3P for water, the topology of methane should be like the following (as presented in `examples/methane/methane.itp`): + ``` [ atomtypes ] ;name btype mass charge ptype sigma epsilon @@ -38,7 +43,9 @@ For example, if one wants to simulate ethane in water, using DeepPotential for m 4 1 2 3 5 5 1 2 3 4 ``` + For comparison, the original topology file generated by `acpype` will be: + ``` ; methane_GMX.itp created by acpype (v: 2021-02-05T22:15:50CET) on Wed Sep 8 01:21:53 2021 @@ -75,45 +82,60 @@ For comparison, the original topology file generated by `acpype` will be: 3 1 5 1 1.0758e+02 3.2635e+02 ; H2 - C1 - H4 4 1 5 1 1.0758e+02 3.2635e+02 ; H3 - C1 - H4 ``` + ### DeepMD Settings + Before running simulations, we need to tell GROMACS to use DeepPotential by setting the environment variable `GMX_DEEPMD_INPUT_JSON`: + ```bash export GMX_DEEPMD_INPUT_JSON=input.json ``` + Then, in your working directories, we have to write `input.json` file: + ```json { - "graph_file": "/path/to/graph.pb", - "type_file": "type.raw", - "index_file": "index.raw", - "lambda": 1.0, - "pbc": false + "graph_file": "/path/to/graph.pb", + "type_file": "type.raw", + "index_file": "index.raw", + "lambda": 1.0, + "pbc": false } ``` + Here is an explanation for these settings: -+ `graph_file` : The graph file (with suffix .pb) generated by `dp freeze` command -+ `type_file` : File to specify DP atom types (in space-separated format). Here, `type.raw` looks like + +- `graph_file` : The graph file (with suffix .pb) generated by `dp freeze` command +- `type_file` : File to specify DP atom types (in space-separated format). Here, `type.raw` looks like + ``` 1 0 0 0 0 ``` -+ `index_file` : File containing indices of DP atoms (in space-separated format), which should be consistent with the indices' order in .gro file but **starting from zero**. Here, `index.raw` looks like + +- `index_file` : File containing indices of DP atoms (in space-separated format), which should be consistent with the indices' order in .gro file but **starting from zero**. Here, `index.raw` looks like + ``` 0 1 2 3 4 ``` -+ `lambda`: Optional, default 1.0. Used in alchemical calculations. -+ `pbc`: Optional, default true. If true, the GROMACS periodic condition is passed to DeepMD. + +- `lambda`: Optional, default 1.0. Used in alchemical calculations. +- `pbc`: Optional, default true. If true, the GROMACS periodic condition is passed to DeepMD. ### Run Simulation + Finally, you can run GROMACS using `gmx mdrun` as usual. ## All-atom DP Simulation + This part gives an example of how to simulate all atoms described by a DeepPotential with Gromacs, taking water as an example. Instead of using `[ exclusions ]` to turn off the non-bonded energies, we can simply do this by setting LJ parameters (i.e. epsilon and sigma) and partial charges to 0, as shown in `examples/water/gmx/water.top`: + ``` [ atomtypes ] ; name at.num mass charge ptype sigma epsilon HW 1 1.008 0.0000 A 0.00000e+00 0.00000e+00 OW 8 16.00 0.0000 A 0.00000e+00 0.00000e+00 ``` + As mentioned in the above section, `input.json` and relevant files (`index.raw`, `type.raw`) should also be created. Then, we can start the simulation under the NVT ensemble and plot the radial distribution function (RDF) by `gmx rdf` command. We can see that the RDF given by Gromacs+DP matches perfectly with Lammps+DP, which further provides an evidence on the validity of our simulation. ![rdf](../../examples/water/gmx/rdf.png) diff --git a/doc/third-party/ipi.md b/doc/third-party/ipi.md index 59decdf3bb..84a972d885 100644 --- a/doc/third-party/ipi.md +++ b/doc/third-party/ipi.md @@ -1,30 +1,36 @@ # Run path-integral MD with i-PI + The i-PI works in a client-server model. The i-PI provides the server for integrating the replica positions of atoms, while the DeePMD-kit provides a client named `dp_ipi` that computes the interactions (including energy, forces and virials). The server and client communicate via the Unix domain socket or the Internet socket. Installation instructions for i-PI can be found [here](../install/install-ipi.md). The client can be started by + ```bash i-pi input.xml & dp_ipi water.json ``` + It is noted that multiple instances of the client allow for computing, in parallel, the interactions of multiple replicas of the path-integral MD. `water.json` is the parameter file for the client `dp_ipi`, and an example is provided: + ```json { - "verbose": false, - "use_unix": true, - "port": 31415, - "host": "localhost", - "graph_file": "graph.pb", - "coord_file": "conf.xyz", - "atom_type" : { - "OW": 0, - "HW1": 1, - "HW2": 1 - } + "verbose": false, + "use_unix": true, + "port": 31415, + "host": "localhost", + "graph_file": "graph.pb", + "coord_file": "conf.xyz", + "atom_type": { + "OW": 0, + "HW1": 1, + "HW2": 1 + } } ``` + The option **`use_unix`** is set to `true` to activate the Unix domain socket, otherwise, the Internet socket is used. The option **`port`** should be the same as that in input.xml: + ```xml 31415 ``` diff --git a/doc/third-party/lammps-command.md b/doc/third-party/lammps-command.md index 150d755795..63f9d8e3bd 100644 --- a/doc/third-party/lammps-command.md +++ b/doc/third-party/lammps-command.md @@ -1,6 +1,7 @@ # Run MD with LAMMPS ## units + All units in LAMMPS except `lj` are supported. `lj` is not supported. The most commonly used units are `metal`, since the internal units of distance, energy, force, and charge in DeePMD-kit are `\AA`, `eV`, `eV / \AA`, and `proton charge`, respectively. These units are consistent with the `metal` units in LAMMPS. @@ -34,11 +35,12 @@ The DeePMD-kit package provides the pair_style `deepmd` ```lammps pair_style deepmd models ... keyword value ... ``` + - deepmd = style of this pair_style - models = frozen model(s) to compute the interaction. -If multiple models are provided, then only the first model serves to provide energy and force prediction for each timestep of molecular dynamics, -and the model deviation will be computed among all models every `out_freq` timesteps. -- keyword = *out_file* or *out_freq* or *fparam* or *fparam_from_compute* or *aparam_from_compute* or *atomic* or *relative* or *relative_v* or *aparam* or *ttm* + If multiple models are provided, then only the first model serves to provide energy and force prediction for each timestep of molecular dynamics, + and the model deviation will be computed among all models every `out_freq` timesteps. +- keyword = _out_file_ or _out_freq_ or _fparam_ or _fparam_from_compute_ or _aparam_from_compute_ or _atomic_ or _relative_ or _relative_v_ or _aparam_ or _ttm_ 
     out_file value = filename
         filename = The file name for the model deviation output. Default is model_devi.out
@@ -63,6 +65,7 @@ and the model deviation will be computed among all models every `out_freq` times
### Examples + ```lammps pair_style deepmd graph.pb pair_style deepmd graph.pb fparam 1.2 @@ -77,6 +80,7 @@ compute 1 all ke/atom ``` ### Description + Evaluate the interaction of the system by using [Deep Potential][DP] or [Deep Potential Smooth Edition][DP-SE]. It is noticed that deep potential is not a "pairwise" interaction, but a multi-body interaction. This pair style takes the deep potential defined in a model file that usually has the .pb extension. The model can be trained and frozen by package [DeePMD-kit](https://github.com/deepmodeling/deepmd-kit), which can have either double or single float precision interface. @@ -107,8 +111,8 @@ If the training parameter {ref}`type_map ` is not set, atom name Spin is specified by keywords `virtual_len` and `spin_norm`. If the keyword `virtual_len` is set, the distance between virtual atom and its corresponding real atom for each type of magnetic atoms will be fed to the model as the spin parameters. If the keyword `spin_norm` is set, the magnitude of the magnetic moment for each type of magnetic atoms will be fed to the model as the spin parameters. ### Restrictions -- The `deepmd` pair style 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. +- The `deepmd` pair style 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. ## Compute tensorial properties @@ -117,6 +121,7 @@ The DeePMD-kit package provides the compute `deeptensor/atom` for computing atom ```lammps compute ID group-ID deeptensor/atom model_file ``` + - ID: user-assigned name of the computation - group-ID: ID of the group of atoms to compute - deeptensor/atom: the style of this compute @@ -125,27 +130,33 @@ compute ID group-ID deeptensor/atom model_file At this time, the training parameter {ref}`type_map ` will be mapped to LAMMPS atom types. ### Examples + ```lammps compute dipole all deeptensor/atom dipole.pb ``` + The result of the compute can be dumped to trajectory file by + ```lammps dump 1 all custom 100 water.dump id type c_dipole[1] c_dipole[2] c_dipole[3] ``` ### Restrictions + - 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 + 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 + ```lammps pair_style deepmd graph.pb pair_coeff * * kspace_style pppm 1.0e-5 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" @@ -157,9 +168,11 @@ $$dvatom=-\sum_{m}( \mathbf{r}_n- \mathbf{r}_m) \frac{de_m}{d\mathbf{r}_n}$$ Where $\mathbf{r}_n$ is the atomic position of nth atom, $\mathbf{v}_n$ velocity of the atom and $\frac{de_m}{d\mathbf{r}_n}$ the derivative of the atomic energy. In LAMMPS one can get the per-atom stress using the command `centroid/stress/atom`: + ```lammps compute ID group-ID centroid/stress/atom NULL virial ``` + see [LAMMPS doc page](https://docs.lammps.org/compute_stress_atom.html#thompson2) for more details on the meaning of the keywords. :::{versionchanged} v2.2.3 @@ -167,20 +180,25 @@ v2.2.2 or previous versions passed per-atom stress (`cvatom`) with the per-atom ::: ### Examples + In order of computing the 9-component per-atom stress + ```lammps compute stress all centroid/stress/atom NULL virial ``` + Thus `c_stress` is an array with 9 components in the order `xx,yy,zz,xy,xz,yz,yx,zx,zy`. 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 + Using a per-atom stress tensor one can, for example, compute the heat flux defined as: $$\mathbf J = \sum_n e_n \mathbf v_n + \sum_{n,m} ( \mathbf r_m- \mathbf r_n) \frac{de_m}{d\mathbf r_n} \mathbf v_n$$ to compute the heat flux with LAMMPS: + ```lammps compute ke_ID all ke/atom compute pe_ID all pe/atom @@ -196,10 +214,10 @@ compute pe all pe/atom compute stress all centroid/stress/atom NULL virial compute flux all heat/flux ke pe stress ``` + `c_flux` is a global vector of length 6. The first three components are the $x$, $y$ and $z$ components of the full heat flux vector. The others are the components of the so-called convective portion, see [LAMMPS doc page](https://docs.lammps.org/compute_heat_flux.html) for more detailes. If you use these features 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) - -[DP]:https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.143001 -[DP-SE]:https://dl.acm.org/doi/10.5555/3327345.3327356 +[DP]: https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.143001 +[DP-SE]: https://dl.acm.org/doi/10.5555/3327345.3327356 diff --git a/doc/third-party/out-of-deepmd-kit.md b/doc/third-party/out-of-deepmd-kit.md index 2ebed6fb46..3eb722c040 100644 --- a/doc/third-party/out-of-deepmd-kit.md +++ b/doc/third-party/out-of-deepmd-kit.md @@ -11,6 +11,7 @@ An [OpenMM](https://github.com/openmm/openmm) plugin is provided from [JingHuang Starting from [AmberTools24](https://ambermd.org/), `sander` includes an interface to the DeePMD-kit, which implements the [Deep Potential Range Corrected (DPRc) correction](../model/dprc.md). The DPRc model and the interface were developed by the [York Lab](https://theory.rutgers.edu/) from Rutgers University. More details are available in + - [Amber Reference Manuals](https://ambermd.org/Manuals.php), providing documentation for how to enable the interface and the `&dprc` namelist; - [GitLab RutgersLBSR/AmberDPRc](https://gitlab.com/RutgersLBSR/AmberDPRc/), providing examples mdin files; - [DP-Amber](https://github.com/njzjz/dpamber/), a tiny tool to convert Amber trajectory to DPRc training data; diff --git a/doc/train/finetuning.md b/doc/train/finetuning.md index e4fa00e23d..011db0bf9f 100644 --- a/doc/train/finetuning.md +++ b/doc/train/finetuning.md @@ -36,6 +36,7 @@ such as {ref}`descriptor `, {ref}`fitting_net ` part in `input.json` to perform finetuning: + ```json "model": { "type_map": ["O", "H"], diff --git a/doc/train/gpu-limitations.md b/doc/train/gpu-limitations.md index dee606c2a3..92577fd65c 100644 --- a/doc/train/gpu-limitations.md +++ b/doc/train/gpu-limitations.md @@ -1,6 +1,7 @@ # Known limitations of using GPUs {{ tensorflow_icon }} If you use DeePMD-kit in a GPU environment, the acceptable value range of some variables is additionally restricted compared to the CPU environment due to the software's GPU implementations: + 1. The number of atom types of a given system must be less than 128. 2. The maximum distance between an atom and its neighbors must be less than 128. It can be controlled by setting the rcut value of training parameters. 3. Theoretically, the maximum number of atoms that a single GPU can accept is about 10,000,000. However, this value is limited by the GPU memory size currently, usually within 1000,000 atoms even in the model compression mode. diff --git a/doc/train/multi-task-training-pt.md b/doc/train/multi-task-training-pt.md index d1d0f9cd0d..284ecf9a27 100644 --- a/doc/train/multi-task-training-pt.md +++ b/doc/train/multi-task-training-pt.md @@ -3,6 +3,7 @@ :::{note} **Supported backends**: PyTorch {{ pytorch_icon }} ::: + ## Theory @@ -10,6 +11,7 @@ The multi-task training process can simultaneously handle different datasets with properties that cannot be fitted in one network (e.g. properties from DFT calculations under different exchange-correlation functionals or different basis sets). These datasets are denoted by $\boldsymbol x^{(1)}, \dots, \boldsymbol x^{(n_t)}$. For each dataset, a training task is defined as + ```math \min_{\boldsymbol \theta} L^{(t)} (\boldsymbol x^{(t)}; \boldsymbol \theta^{(t)}, \tau), \quad t=1, \dots, n_t. ``` @@ -29,6 +31,7 @@ In particular, it makes multi-GPU parallel training and even tasks beyond DFT po enabling larger-scale and more general multi-task training to obtain more general pre-trained models. ## Perform the multi-task training using PyTorch + Training on multiple data sets (each data set contains several data systems) can be performed in multi-task mode, typically with one common descriptor and multiple specific fitting nets for each data set. To proceed, one need to change the representation of the model definition in the input script. @@ -37,34 +40,35 @@ define the shared parameters of the model part {ref}`shared_dict `: The parameter definition of the shared part, including various descriptors, -type maps (or even fitting nets can be shared). Each module can be defined with a user-defined `part_key`, such as `my_descriptor`. -The content needs to align with the corresponding definition in the single-task training model component, such as the definition of the descriptor. + type maps (or even fitting nets can be shared). Each module can be defined with a user-defined `part_key`, such as `my_descriptor`. + The content needs to align with the corresponding definition in the single-task training model component, such as the definition of the descriptor. - {ref}`model/model_dict `: The core definition of the model part and the explanation of sharing rules, -starting with user-defined model name keys `model_key`, such as `my_model_1`. -Each model part needs to align with the components of the single-task training {ref}`model `, but with the following sharing rules: + starting with user-defined model name keys `model_key`, such as `my_model_1`. + Each model part needs to align with the components of the single-task training {ref}`model `, but with the following sharing rules: - - If you want to share the current model component with other tasks, which should be part of the {ref}`model/shared_dict `, -you can directly fill in the corresponding `part_key`, such as -```"descriptor": "my_descriptor", ``` -to replace the previous detailed parameters. Here, you can also specify the shared_level, such as -```"descriptor": "my_descriptor:shared_level", ``` -and use the user-defined integer `shared_level` in the code to share the corresponding module to varying degrees -(default is to share all parameters, i.e., `shared_level`=0). -The parts that are exclusive to each model can be written following the previous definition. + you can directly fill in the corresponding `part_key`, such as + `"descriptor": "my_descriptor", ` + to replace the previous detailed parameters. Here, you can also specify the shared_level, such as + `"descriptor": "my_descriptor:shared_level", ` + and use the user-defined integer `shared_level` in the code to share the corresponding module to varying degrees + (default is to share all parameters, i.e., `shared_level`=0). + The parts that are exclusive to each model can be written following the previous definition. - {ref}`loss_dict `: The loss settings corresponding to each task model, specified by the `model_key`. -Each {ref}`loss_dict/model_key ` contains the corresponding loss settings, -which are the same as the definition in single-task training {ref}``. + Each {ref}`loss_dict/model_key ` contains the corresponding loss settings, + which are the same as the definition in single-task training {ref}``. - {ref}`training/data_dict `: The data settings corresponding to each task model, specified by the `model_key`. -Each `training/data_dict/model_key` contains the corresponding `training_data` and `validation_data` settings, -which are the same as the definition in single-task training {ref}`training_data ` and {ref}`validation_data `. + Each `training/data_dict/model_key` contains the corresponding `training_data` and `validation_data` settings, + which are the same as the definition in single-task training {ref}`training_data ` and {ref}`validation_data `. - (Optional) {ref}`training/model_prob `: The sampling weight settings corresponding to each `model_key`, i.e., the probability weight in the training step. -You can specify any positive real number weight for each task. The higher the weight, the higher the probability of being sampled in each training. -This setting is optional, and if not set, tasks will be sampled with equal weights. + You can specify any positive real number weight for each task. The higher the weight, the higher the probability of being sampled in each training. + This setting is optional, and if not set, tasks will be sampled with equal weights. An example input for multi-task training two models in water system is shown as following: + ```{literalinclude} ../../examples/water_multi_task/pytorch_example/input_torch.json :language: json :linenos: @@ -76,6 +80,7 @@ To finetune based on the checkpoint `model.pt` after the multi-task pre-training users only need to prepare the normal input for single-task training `input_single.json`, and then select one of the trained model's task names `model_key`. Run the following command: + ```bash $ dp --pt train input_single.json --finetune model.pt --model-branch model_key ``` diff --git a/doc/train/multi-task-training-tf.md b/doc/train/multi-task-training-tf.md index 47fb1cc1da..0f745958eb 100644 --- a/doc/train/multi-task-training-tf.md +++ b/doc/train/multi-task-training-tf.md @@ -3,6 +3,7 @@ :::{note} **Supported backends**: TensorFlow {{ tensorflow_icon }} ::: + ## Theory @@ -10,6 +11,7 @@ The multi-task training process can simultaneously handle different datasets with properties that cannot be fitted in one network (e.g. properties from DFT calculations under different exchange-correlation functionals or different basis sets). These datasets are denoted by $\boldsymbol x^{(1)}, \dots, \boldsymbol x^{(n_t)}$. For each dataset, a training task is defined as + ```math \min_{\boldsymbol \theta} L^{(t)} (\boldsymbol x^{(t)}; \boldsymbol \theta^{(t)}, \tau), \quad t=1, \dots, n_t. ``` @@ -20,24 +22,26 @@ At each training step, a task is randomly picked from ${1, \dots, n_t}$, and the If different fitting networks have the same architecture, they can share the parameters of some layers to improve training efficiency.[^1] -[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). +[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). ## Perform the multi-task training + Training on multiple data sets (each data set contains several data systems) can be performed in multi-task mode, with one common descriptor and multiple specific fitting nets for each data set. One can simply switch the following parameters in training input script to perform multi-task mode: + - {ref}`fitting_net ` --> {ref}`fitting_net_dict `, -each key of which can be one individual fitting net. -- {ref}`training_data `, {ref}`validation_data ` ---> {ref}`data_dict `, each key of which can be one individual data set contains -several data systems for corresponding fitting net, the keys must be consistent with those in -{ref}`fitting_net_dict `. + each key of which can be one individual fitting net. +- {ref}`training_data `, {ref}`validation_data ` + --> {ref}`data_dict `, each key of which can be one individual data set contains + several data systems for corresponding fitting net, the keys must be consistent with those in + {ref}`fitting_net_dict `. - {ref}`loss ` --> {ref}`loss_dict `, each key of which can be one individual loss setting -for corresponding fitting net, the keys must be consistent with those in -{ref}`fitting_net_dict `, if not set, the corresponding fitting net will use the default loss. + for corresponding fitting net, the keys must be consistent with those in + {ref}`fitting_net_dict `, if not set, the corresponding fitting net will use the default loss. - (Optional) {ref}`fitting_weight `, each key of which can be a non-negative integer or float, -deciding the chosen probability for corresponding fitting net in training, if not set or invalid, -the corresponding fitting net will not be used. + deciding the chosen probability for corresponding fitting net in training, if not set or invalid, + the corresponding fitting net will not be used. The training procedure will automatically choose single-task or multi-task mode, based on the above parameters. Note that parameters of single-task mode and multi-task mode can not be mixed. @@ -45,6 +49,7 @@ Note that parameters of single-task mode and multi-task mode can not be mixed. An example input for training energy and dipole in water system can be found here: [multi-task input on water](../../examples/water_multi_task/ener_dipole/input.json). The supported descriptors for multi-task mode are listed: + - {ref}`se_a (se_e2_a) ` - {ref}`se_r (se_e2_r) ` - {ref}`se_at (se_e3) ` @@ -53,6 +58,7 @@ The supported descriptors for multi-task mode are listed: - {ref}`hybrid ` The supported fitting nets for multi-task mode are listed: + - {ref}`ener ` - {ref}`dipole ` - {ref}`polar ` @@ -60,12 +66,14 @@ The supported fitting nets for multi-task mode are listed: The output of `dp freeze` command in multi-task mode can be seen in [freeze command](../freeze/freeze.md). ## Initialization from pretrained multi-task model + For advance training in multi-task mode, one can first train the descriptor on several upstream datasets and then transfer it on new downstream ones with newly added fitting nets. At the second step, you can also inherit some fitting nets trained on upstream datasets, by merely adding fitting net keys in {ref}`fitting_net_dict ` and optional fitting net weights in {ref}`fitting_weight `. Take [multi-task input on water](../../examples/water_multi_task/ener_dipole/input.json) again for example. You can first train a multi-task model using input script with the following {ref}`model ` part: + ```json "model": { "type_map": ["O", "H"], @@ -89,12 +97,16 @@ You can first train a multi-task model using input script with the following {re }, } ``` + After training, you can freeze this multi-task model into one unit graph: + ```bash $ dp freeze -o graph.pb --united-model ``` + Then if you want to transfer the trained descriptor and some fitting nets (take `water_ener` for example) to newly added datasets with new fitting net `water_ener_2`, you can modify the {ref}`model ` part of the new input script in a more simplified way: + ```json "model": { "type_map": ["O", "H"], @@ -108,12 +120,14 @@ you can modify the {ref}`model ` part of the new input script in a more s }, } ``` + It will autocomplete the configurations according to the frozen graph. Note that for newly added fitting net keys, other parts in the input script, including {ref}`data_dict ` and {ref}`loss_dict ` (optionally {ref}`fitting_weight `), should be set explicitly. While for old fitting net keys, it will inherit the old configurations if not set. Finally, you can perform the modified multi-task training from the frozen model with command: + ```bash $ dp train input.json --init_frz_model graph.pb ``` @@ -125,6 +139,7 @@ In this situation, one can set {ref}`model/fitting_net[ener]/layer_name>` to sha The architecture of the layers with the same name should be the same. For example, if one want to share the first and the third layers for two three-hidden-layer fitting networks, the following parameters should be set. + ```json "fitting_net_dict": { "ccsd": { diff --git a/doc/train/parallel-training.md b/doc/train/parallel-training.md index aba2836250..9ea92b4751 100644 --- a/doc/train/parallel-training.md +++ b/doc/train/parallel-training.md @@ -5,6 +5,7 @@ ::: ## TensorFlow Implementation {{ tensorflow_icon }} + Currently, parallel training in tensorflow version is enabled in a synchronized way with help of [Horovod](https://github.com/horovod/horovod). Depending on the number of training processes (according to MPI context) and the number of GPU cards available, DeePMD-kit will decide whether to launch the training in parallel (distributed) mode or in serial mode. Therefore, no additional options are specified in your JSON/YAML input file. @@ -15,6 +16,7 @@ Horovod works in the data-parallel mode, resulting in a larger global batch size The number of decay steps required to achieve the same accuracy can decrease by the number of cards (e.g., 1/2 of steps in the above case), but needs to be scaled manually in the input file. In some cases, it won't work well when scaling the learning rate by worker count in a `linear` way. Then you can try `sqrt` or `none` by setting argument {ref}`scale_by_worker ` like below. + ```json "learning_rate" :{ "scale_by_worker": "none", @@ -27,11 +29,11 @@ In some cases, it won't work well when scaling the learning rate by worker count Testing `examples/water/se_e2_a` on an 8-GPU host, linear acceleration can be observed with the increasing number of cards. | Num of GPU cards | Seconds every 100 samples | Samples per second | Speed up | -| -- | -- | -- | -- | -| 1 | 1.4515 | 68.89 | 1.00 | -| 2 | 1.5962 | 62.65*2 | 1.82 | -| 4 | 1.7635 | 56.71*4 | 3.29 | -| 8 | 1.7267 | 57.91*8 | 6.72 | +| ---------------- | ------------------------- | ------------------ | -------- | +| 1 | 1.4515 | 68.89 | 1.00 | +| 2 | 1.5962 | 62.65\*2 | 1.82 | +| 4 | 1.7635 | 56.71\*4 | 3.29 | +| 8 | 1.7267 | 57.91\*8 | 6.72 | ### How to use @@ -47,13 +49,16 @@ Need to mention, the environment variable `CUDA_VISIBLE_DEVICES` must be set to To maximize the performance, one should follow [FAQ: How to control the parallelism of a job](../troubleshooting/howtoset_num_nodes.md) to control the number of threads. When using MPI with Horovod, `horovodrun` is a simple wrapper around `mpirun`. In the case where fine-grained control over options is passed to `mpirun`, [`mpirun` can be invoked directly](https://horovod.readthedocs.io/en/stable/mpi_include.html), and it will be detected automatically by Horovod, e.g., + ```bash CUDA_VISIBLE_DEVICES=4,5,6,7 mpirun -l -launcher=fork -hosts=localhost -np 4 \ dp train --mpi-log=workers input.json ``` + this is sometimes necessary for an HPC environment. Whether distributed workers are initiated can be observed in the "Summary of the training" section in the log (`world size` > 1, and `distributed`). + ``` [0] DEEPMD INFO ---Summary of the training--------------------------------------- [0] DEEPMD INFO distributed @@ -72,6 +77,7 @@ Whether distributed workers are initiated can be observed in the "Summary of the ### Logging What's more, 2 command-line arguments are defined to control the logging behavior when performing parallel training with MPI. + ``` optional arguments: -l LOG_PATH, --log-path LOG_PATH @@ -88,19 +94,20 @@ optional arguments: ## PyTorch Implementation {{ pytorch_icon }} -Currently, parallel training in pytorch version is implemented in the form of PyTorch Distributed Data Parallelism [DDP](https://pytorch.org/docs/stable/generated/torch.nn.parallel.DistributedDataParallel.html). +Currently, parallel training in pytorch version is implemented in the form of PyTorch Distributed Data Parallelism [DDP](https://pytorch.org/docs/stable/generated/torch.nn.parallel.DistributedDataParallel.html). DeePMD-kit will decide whether to launch the training in parallel (distributed) mode or in serial mode depending on your execution command. ### Dataloader and Dataset + One of the major differences between two backends during training is that the PyTorch version employs a multi-threaded data loading utility [DataLoader](https://pytorch.org/docs/stable/data.html). We utilize the PyTorch framework and have designed and implemented a multiprocessing data processing and loading system called DpLoaderSet based on torch DataLoader and Dataset. - First, we establish a DeepmdData class for each system, which is consistent with the TensorFlow version in this level. Then, we create a dataloader for each system, resulting in the same number of dataloaders as the number of systems. Next, we create a dataset for the dataloaders obtained in the previous step. This allows us to query the data for each system through this dataset, while the iteration pointers for each system are maintained by their respective dataloaders. Finally, a dataloader is created for the outermost dataset. -We achieve custom sampling methods using a weighted sampler. The length of the sampler is set to total_batch_num * num_workers.The parameter "num_workers" defines the number of threads involved in multi-threaded loading, which can be modified by setting the environment variable NUM_WORKERS (default: min(8, ncpus)). +We achieve custom sampling methods using a weighted sampler. The length of the sampler is set to total_batch_num \* num_workers.The parameter "num_workers" defines the number of threads involved in multi-threaded loading, which can be modified by setting the environment variable NUM_WORKERS (default: min(8, ncpus)). > **Note** The underlying dataloader will use a distributed sampler to ensure that each GPU receives batches with different content in parallel mode, which will use sequential sampler in serial mode. In the TensorFlow version, Horovod shuffles the dataset using different random seeds for the same purpose.. + ```mermaid flowchart LR @@ -174,6 +181,7 @@ torchrun --rdzv_endpoint=node0:12321 --nnodes=2 --nproc_per_node=4 --node_rank=0 # On node 1: torchrun --rdzv_endpoint=node0:12321 --nnodes=2 --nproc_per_node=4 --node_rank=1 --no_python dp --pt train tests/water/se_e2_a.json ``` + > **Note** Set environment variables to tune [CPU specific optimizations](https://pytorch.org/tutorials/recipes/recipes/tuning_guide.html#cpu-specific-optimizations) in advance. > **Note** for developers: `torchrun` by default passes settings as environment variables [(list here)](https://pytorch.org/docs/stable/elastic/run.html#environment-variables). diff --git a/doc/train/tensorboard.md b/doc/train/tensorboard.md index a6cfdccb68..7b41c004ce 100644 --- a/doc/train/tensorboard.md +++ b/doc/train/tensorboard.md @@ -12,10 +12,10 @@ experimentation. Full instructions for TensorBoard can be found DeePMD-kit can now use most of the interesting features enabled by TensorBoard! -* **Tracking and visualizing metrics,** such as l2_loss, l2_energy_loss and l2_force_loss -* **Visualizing the model graph** (ops and layers) -* **Viewing histograms of weights, biases, or other tensors as they change over time.** -* **Viewing summaries of trainable variables** +- **Tracking and visualizing metrics,** such as l2_loss, l2_energy_loss and l2_force_loss +- **Visualizing the model graph** (ops and layers) +- **Viewing histograms of weights, biases, or other tensors as they change over time.** +- **Viewing summaries of trainable variables** @@ -84,6 +84,7 @@ tensorboard --logdir path/to/logs ![DeePMD-kit distribution](../images/tensorboard-distribution.png) ### Viewing summaries of trainable variables + ![DeePMD-kit scalar](../images/tensorboard-scalar.png) ## Attention diff --git a/doc/train/training-advanced.md b/doc/train/training-advanced.md index 4940b77fa7..a0f6759256 100644 --- a/doc/train/training-advanced.md +++ b/doc/train/training-advanced.md @@ -7,21 +7,26 @@ In this section, we will take `$deepmd_source_dir/examples/water/se_e2_a/input.j ### Theory The learning rate $\gamma$ decays exponentially: + ```math \gamma(\tau) = \gamma^0 r ^ {\lfloor \tau/s \rfloor}, ``` + where $\tau \in \mathbb{N}$ is the index of the training step, $\gamma^0 \in \mathbb{R}$ is the learning rate at the first step, and the decay rate $r$ is given by + ```math r = {\left(\frac{\gamma^{\text{stop}}}{\gamma^0}\right )} ^{\frac{s}{\tau^{\text{stop}}}}, ``` + where $\tau^{\text{stop}} \in \mathbb{N}$, $\gamma^{\text{stop}} \in \mathbb{R}$, and $s \in \mathbb{N}$ are the stopping step, the stopping learning rate, and the decay steps, respectively, all of which are hyperparameters provided in advance. [^1] -[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). +[^1]: This section is built upon 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, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/). ### Instructions The {ref}`learning_rate ` section in `input.json` is given as follows + ```json "learning_rate" :{ "type": "exp", @@ -31,17 +36,19 @@ The {ref}`learning_rate ` section in `input.json` is given as fol "_comment": "that's all" } ``` -* {ref}`start_lr ` gives the learning rate at the beginning of the training. -* {ref}`stop_lr ` gives the learning rate at the end of the training. It should be small enough to ensure that the network parameters satisfactorily converge. -* During the training, the learning rate decays exponentially from {ref}`start_lr ` to {ref}`stop_lr ` following the formula: - ``` - lr(t) = start_lr * decay_rate ^ ( t / decay_steps ) - ``` +- {ref}`start_lr ` gives the learning rate at the beginning of the training. +- {ref}`stop_lr ` gives the learning rate at the end of the training. It should be small enough to ensure that the network parameters satisfactorily converge. +- During the training, the learning rate decays exponentially from {ref}`start_lr ` to {ref}`stop_lr ` following the formula: + + ``` + lr(t) = start_lr * decay_rate ^ ( t / decay_steps ) + ``` ## Training parameters Other training parameters are given in the {ref}`training ` section. + ```json "training": { "training_data": { @@ -65,15 +72,18 @@ Other training parameters are given in the {ref}`training ` section. "save_freq": 1000 } ``` + The sections {ref}`training_data ` and {ref}`validation_data ` give the training dataset and validation dataset, respectively. Taking the training dataset for example, the keys are explained below: -* {ref}`systems ` provide paths of the training data systems. DeePMD-kit allows you to provide multiple systems with different numbers of atoms. This key can be a `list` or a `str`. - * `list`: {ref}`systems ` gives the training data systems. - * `str`: {ref}`systems ` should be a valid path. DeePMD-kit will recursively search all data systems in this path. -* At each training step, DeePMD-kit randomly picks {ref}`batch_size ` frame(s) from one of the systems. The probability of using a system is by default in proportion to the number of batches in the system. More options are available for automatically determining the probability of using systems. One can set the key {ref}`auto_prob ` to - * `"prob_uniform"` all systems are used with the same probability. - * `"prob_sys_size"` the probability of using a system is proportional to its size (number of frames). - * `"prob_sys_size; sidx_0:eidx_0:w_0; sidx_1:eidx_1:w_1;..."` the `list` of systems is divided into blocks. Block `i` has systems ranging from `sidx_i` to `eidx_i`. The probability of using a system from block `i` is proportional to `w_i`. Within one block, the probability of using a system is proportional to its size. -* An example of using `"auto_prob"` is given below. The probability of using `systems[2]` is 0.4, and the sum of the probabilities of using `systems[0]` and `systems[1]` is 0.6. If the number of frames in `systems[1]` is twice of `system[0]`, then the probability of using `system[1]` is 0.4 and that of `system[0]` is 0.2. + +- {ref}`systems ` provide paths of the training data systems. DeePMD-kit allows you to provide multiple systems with different numbers of atoms. This key can be a `list` or a `str`. + - `list`: {ref}`systems ` gives the training data systems. + - `str`: {ref}`systems ` should be a valid path. DeePMD-kit will recursively search all data systems in this path. +- At each training step, DeePMD-kit randomly picks {ref}`batch_size ` frame(s) from one of the systems. The probability of using a system is by default in proportion to the number of batches in the system. More options are available for automatically determining the probability of using systems. One can set the key {ref}`auto_prob ` to + - `"prob_uniform"` all systems are used with the same probability. + - `"prob_sys_size"` the probability of using a system is proportional to its size (number of frames). + - `"prob_sys_size; sidx_0:eidx_0:w_0; sidx_1:eidx_1:w_1;..."` the `list` of systems is divided into blocks. Block `i` has systems ranging from `sidx_i` to `eidx_i`. The probability of using a system from block `i` is proportional to `w_i`. Within one block, the probability of using a system is proportional to its size. +- An example of using `"auto_prob"` is given below. The probability of using `systems[2]` is 0.4, and the sum of the probabilities of using `systems[0]` and `systems[1]` is 0.6. If the number of frames in `systems[1]` is twice of `system[0]`, then the probability of using `system[1]` is 0.4 and that of `system[0]` is 0.2. + ```json "training_data": { "systems": ["../data_water/data_0/", "../data_water/data_1/", "../data_water/data_2/"], @@ -81,7 +91,9 @@ The sections {ref}`training_data ` and {ref}`validation_ "batch_size": "auto" } ``` -* The probability of using systems can also be specified explicitly with key {ref}`sys_probs ` which is a list having the length of the number of systems. For example + +- The probability of using systems can also be specified explicitly with key {ref}`sys_probs ` which is a list having the length of the number of systems. For example + ```json "training_data": { "systems": ["../data_water/data_0/", "../data_water/data_1/", "../data_water/data_2/"], @@ -89,34 +101,40 @@ The sections {ref}`training_data ` and {ref}`validation_ "batch_size": "auto:32" } ``` -* The key {ref}`batch_size ` specifies the number of frames used to train or validate the model in a training step. It can be set to - * `list`: the length of which is the same as the {ref}`systems`. The batch size of each system is given by the elements of the list. - * `int`: all systems use the same batch size. - * `"auto"`: the same as `"auto:32"`, see `"auto:N"` - * `"auto:N"`: automatically determines the batch size so that the {ref}`batch_size ` times the number of atoms in the system is no less than `N`. -* The key {ref}`numb_batch ` in {ref}`validate_data ` gives the number of batches of model validation. Note that the batches may not be from the same system + +- The key {ref}`batch_size ` specifies the number of frames used to train or validate the model in a training step. It can be set to + - `list`: the length of which is the same as the {ref}`systems`. The batch size of each system is given by the elements of the list. + - `int`: all systems use the same batch size. + - `"auto"`: the same as `"auto:32"`, see `"auto:N"` + - `"auto:N"`: automatically determines the batch size so that the {ref}`batch_size ` times the number of atoms in the system is no less than `N`. +- The key {ref}`numb_batch ` in {ref}`validate_data ` gives the number of batches of model validation. Note that the batches may not be from the same system The section {ref}`mixed_precision ` specifies the mixed precision settings, which will enable the mixed precision training workflow for DeePMD-kit. The keys are explained below: -* {ref}`output_prec ` precision used in the output tensors, only `float32` is supported currently. -* {ref}`compute_prec ` precision used in the computing tensors, only `float16` is supported currently. -Note there are several limitations about mixed precision training: -* Only {ref}`se_e2_a ` type descriptor is supported by the mixed precision training workflow. -* The precision of the embedding net and the fitting net are forced to be set to `float32`. + +- {ref}`output_prec ` precision used in the output tensors, only `float32` is supported currently. +- {ref}`compute_prec ` precision used in the computing tensors, only `float16` is supported currently. + Note there are several limitations about mixed precision training: +- Only {ref}`se_e2_a ` type descriptor is supported by the mixed precision training workflow. +- The precision of the embedding net and the fitting net are forced to be set to `float32`. Other keys in the {ref}`training ` section are explained below: -* {ref}`numb_steps ` The number of training steps. -* {ref}`seed ` The random seed for getting frames from the training data set. -* {ref}`disp_file ` The file for printing learning curve. -* {ref}`disp_freq ` The frequency of printing learning curve. Set in the unit of training steps -* {ref}`save_freq ` The frequency of saving checkpoint. + +- {ref}`numb_steps ` The number of training steps. +- {ref}`seed ` The random seed for getting frames from the training data set. +- {ref}`disp_file ` The file for printing learning curve. +- {ref}`disp_freq ` The frequency of printing learning curve. Set in the unit of training steps +- {ref}`save_freq ` The frequency of saving checkpoint. ## Options and environment variables Several command line options can be passed to `dp train`, which can be checked with + ```bash $ dp train --help ``` + An explanation will be provided + ``` positional arguments: INPUT the input json database @@ -146,16 +164,16 @@ To maximize the performance, one should follow [FAQ: How to control the parallel One can set other environmental variables: -| Environment variables | Allowed value | Default value | Usage | -| --------------------- | ---------------------- | ------------- | -------------------------- | -| DP_INTERFACE_PREC | `high`, `low` | `high` | Control high (double) or low (float) precision of training. | -| DP_AUTO_PARALLELIZATION | 0, 1 | 0 | Enable auto parallelization for CPU operators. | -| DP_JIT | 0, 1 | 0 | Enable JIT. Note that this option may either improve or decrease the performance. Requires TensorFlow supports JIT. | - +| Environment variables | Allowed value | Default value | Usage | +| ----------------------- | ------------- | ------------- | ------------------------------------------------------------------------------------------------------------------- | +| DP_INTERFACE_PREC | `high`, `low` | `high` | Control high (double) or low (float) precision of training. | +| DP_AUTO_PARALLELIZATION | 0, 1 | 0 | Enable auto parallelization for CPU operators. | +| DP_JIT | 0, 1 | 0 | Enable JIT. Note that this option may either improve or decrease the performance. Requires TensorFlow supports JIT. | ## Adjust `sel` of a frozen model One can use `--init-frz-model` features to adjust (increase or decrease) [`sel`](../model/sel.md) of a existing model. Firstly, one needs to adjust [`sel`](./train-input.rst) in `input.json`. For example, adjust from `[46, 92]` to `[23, 46]`. + ```json "model": { "descriptor": { @@ -163,7 +181,9 @@ One can use `--init-frz-model` features to adjust (increase or decrease) [`sel`] } } ``` + To obtain the new model at once, [`numb_steps`](./train-input.rst) should be set to zero: + ```json "training": { "numb_steps": 0 @@ -171,6 +191,7 @@ To obtain the new model at once, [`numb_steps`](./train-input.rst) should be set ``` Then, one can initialize the training from the frozen model and freeze the new model at once: + ```sh dp train input.json --init-frz-model frozen_model.pb dp freeze -o frozen_model_adjusted_sel.pb diff --git a/doc/train/training.md b/doc/train/training.md index c1e5b89a84..5b7bbd32a8 100644 --- a/doc/train/training.md +++ b/doc/train/training.md @@ -1,17 +1,21 @@ # Train a model Several examples of training can be found in the `examples` directory: + ```bash $ cd $deepmd_source_dir/examples/water/se_e2_a/ ``` After switching to that directory, the training can be invoked by + ```bash $ dp train input.json ``` + where `input.json` is the name of the input script. By default, the verbosity level of the DeePMD-kit is `INFO`, one may see a lot of important information on the code and environment showing on the screen. Among them two pieces of information regarding data systems are worth special notice. + ```bash DEEPMD INFO ---Summary of DataSystem: training ----------------------------------------------- DEEPMD INFO found 3 system(s): @@ -26,9 +30,11 @@ DEEPMD INFO system natoms bch_sz n_bc DEEPMD INFO ../data_water/data_3 192 1 80 1.000 T DEEPMD INFO -------------------------------------------------------------------------------------- ``` + The DeePMD-kit prints detailed information on the training and validation data sets. The data sets are defined by {ref}`training_data ` and {ref}`validation_data ` defined in the {ref}`training ` section of the input script. The training data set is composed of three data systems, while the validation data set is composed by one data system. The number of atoms, batch size, the number of batches in the system and the probability of using the system are all shown on the screen. The last column presents if the periodic boundary condition is assumed for the system. During the training, the error of the model is tested every {ref}`disp_freq ` training steps with the batch used to train the model and with {ref}`numb_btch ` batches from the validating data. The training error and validation error are printed correspondingly in the file {ref}`disp_file ` (default is `lcurve.out`). The batch size can be set in the input script by the key {ref}`batch_size ` in the corresponding sections for the training and validation data set. An example of the output + ```bash # step rmse_val rmse_trn rmse_e_val rmse_e_trn rmse_f_val rmse_f_trn lr 0 3.33e+01 3.41e+01 1.03e+01 1.03e+01 8.39e-01 8.72e-01 1.0e-03 @@ -38,6 +44,7 @@ During the training, the error of the model is tested every {ref}`disp_freq