From 472dc1c4db43a4193dee0ff3b3918f47576e688a Mon Sep 17 00:00:00 2001 From: tuoping Date: Wed, 14 Apr 2021 07:27:14 +0800 Subject: [PATCH 01/66] check html window --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index b392cdbca5..7ce1cd7454 100644 --- a/.gitignore +++ b/.gitignore @@ -26,3 +26,4 @@ venv* .vscode/** _build _templates +testdoc From 35420baabad4cc5d72015bf58ea537e3d8af8aa4 Mon Sep 17 00:00:00 2001 From: tuoping Date: Wed, 14 Apr 2021 08:46:57 +0800 Subject: [PATCH 02/66] change index.rst of branch devel --- doc/index.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 8c1dff0071..9777ce0cdc 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -3,13 +3,20 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +:tocdepth: 3 + DeePMD-kit's documentation ====================================== +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. + +.. Important:: The project DeePMD-kit is licensed under GNU LGPLv3.0. If you use this code in any future publications, please cite this using 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. + +Getting Started +=============== + .. toctree:: :maxdepth: 2 - :caption: Contents: - install use-deepmd-kit From 36adf851bb3ddcc51bee18299806c429a828d4c6 Mon Sep 17 00:00:00 2001 From: tuoping Date: Wed, 14 Apr 2021 14:17:53 +0800 Subject: [PATCH 03/66] Re-structured doc --- doc/index.rst | 60 +++++++++++++++++++++++++++++----- doc/novel-auxiliary-options.md | 17 ---------- 2 files changed, 52 insertions(+), 25 deletions(-) delete mode 100644 doc/novel-auxiliary-options.md diff --git a/doc/index.rst b/doc/index.rst index 8c1dff0071..b5bc321ee8 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -6,25 +6,69 @@ DeePMD-kit's documentation ====================================== +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. + +.. Important:: The project DeePMD-kit is licensed under GNU LGPLv3.0. If you use this code in any future publications, please cite this using 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. + +User Guide +========== + .. toctree:: :maxdepth: 2 - :caption: Contents: - install use-deepmd-kit + tensorboard + whatsnew + Example Gallery + +Data structures and transformations +=================================== + +.. toctree:: + :maxdepth: 2 + + dpdata + + +Input and Output Parameters +=========================== + +.. toctree:: + :maxdepth: 2 + train-input lammps-pair-style-deepmd - novel-auxiliary-options - tensorboard - api + +Programmer Guide +================ + +.. toctree:: + :maxdepth: 2 + developement - application-examples + api +Nuts and bolts +============== + +.. toctree:: + :maxdepth: 2 + + known_issues + +Project Details +=============== + +.. toctree:: + :maxdepth: 2 + + license_and_credits -Indices and tables -================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` + +.. _feedback: +.. _affiliated packages: diff --git a/doc/novel-auxiliary-options.md b/doc/novel-auxiliary-options.md deleted file mode 100644 index 9e92382d10..0000000000 --- a/doc/novel-auxiliary-options.md +++ /dev/null @@ -1,17 +0,0 @@ -# Novel Auxiliary Options -## Type embedding -Instead of training embedding net for each atom pair (regard as G_ij, and turns out to be N^2 networks), we now share a public embedding net (regard as G) and present each atom with a special vector, named as type embedding (v_i). So, our algorithm for generating a description change from G_ij(s_ij) to G(s_ij, v_i, v_j). -1. We obtain the type embedding by a small embedding net, projecting atom type to embedding vector. -2. As for the fitting net, we fix the type embedding and replace individual fitting net with shared fitting net. (while adding type embedding information to its input) - -### Training hyper-parameter -descriptor: -"type" : "se_a_ebd" # for applying share embedding algorithm -"type_filter" : list # network architecture of the small embedding net, which output type embedding -"type_one_side" : bool # when generating descriptor, whether use the centric atom type embedding (true: G(s_ij, v_i, v_j), false: G(s_ij, v_j)) - -fitting_net: -"share_fitting" : bool # if applying share fitting net, set true - - -## Interpolation with tabulated pair potentials From 8dc480bd3a02dcf6014ae84b4fa43ef4ee7a9739 Mon Sep 17 00:00:00 2001 From: tuoping Date: Wed, 14 Apr 2021 16:15:13 +0800 Subject: [PATCH 04/66] Re-structured Doc --- doc/application-examples.md | 5 +++++ doc/conf.py | 4 ++++ doc/index.rst | 30 +++++++++++------------------- 3 files changed, 20 insertions(+), 19 deletions(-) diff --git a/doc/application-examples.md b/doc/application-examples.md index 4fa2674713..bfbc9472a1 100644 --- a/doc/application-examples.md +++ b/doc/application-examples.md @@ -6,3 +6,8 @@ ## MD on different hardware platforms +There is a scheme to generate doc html from python scripts provided in the ../examples/ directory, so that each case in doc has a counter part in ../examples. + +This scheme is implemented with sphinx-gallery. + +Do we want to use this ??? diff --git a/doc/conf.py b/doc/conf.py index b757da9771..3be81a2de2 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -48,6 +48,10 @@ # a list of builtin themes. # html_theme = 'sphinx_rtd_theme' +html_sidebars = { + '**': ['localtoc.html', 'sourcelink.html', 'searchbox.html'], + 'using/windows': ['windowssidebar.html', 'searchbox.html'], +} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/doc/index.rst b/doc/index.rst index e6248a40f9..873445052e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -3,7 +3,6 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -:tocdepth: 3 DeePMD-kit's documentation ====================================== @@ -12,16 +11,10 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r .. Important:: The project DeePMD-kit is licensed under GNU LGPLv3.0. If you use this code in any future publications, please cite this using 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. -<<<<<<< HEAD -User Guide -========== -======= -Getting Started -=============== ->>>>>>> 8ac43e529f20acb8cb0b12307fe1386d9311ddeb .. toctree:: :maxdepth: 2 + :caption: User Guide install use-deepmd-kit @@ -29,46 +22,45 @@ Getting Started whatsnew Example Gallery -Data structures and transformations -=================================== + .. toctree:: :maxdepth: 2 + :caption: Data structures - dpdata + convert-data -Input and Output Parameters -=========================== .. toctree:: :maxdepth: 2 + :caption: I/O Parameters train-input lammps-pair-style-deepmd -Programmer Guide -================ + .. toctree:: :maxdepth: 2 + :caption: Programmer Guide developement api -Nuts and bolts -============== + .. toctree:: :maxdepth: 2 + :caption: Nuts and bolts known_issues -Project Details -=============== + .. toctree:: :maxdepth: 2 + :caption: Project Details license_and_credits From f7c000fca559ea497b33f761fb3d222f64dfa345 Mon Sep 17 00:00:00 2001 From: tuoping Date: Wed, 14 Apr 2021 16:17:26 +0800 Subject: [PATCH 05/66] Re-structured Doc --- doc/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/index.rst b/doc/index.rst index 873445052e..4f105ce276 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -26,7 +26,7 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r .. toctree:: :maxdepth: 2 - :caption: Data structures + :caption: Data Format convert-data From 6e92359ca5e78d131f0c08dc8f6720fcedf88f8a Mon Sep 17 00:00:00 2001 From: tuoping Date: Wed, 14 Apr 2021 17:13:43 +0800 Subject: [PATCH 06/66] Re-structured Doc --- doc/index.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/index.rst b/doc/index.rst index 4f105ce276..d0bbf5402d 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -62,7 +62,8 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r :maxdepth: 2 :caption: Project Details - license_and_credits + license + credits * :ref:`genindex` From d2bd1eaf6c67c6e64fae8b15e1aaad595309e5a2 Mon Sep 17 00:00:00 2001 From: tuoping Date: Wed, 14 Apr 2021 17:17:56 +0800 Subject: [PATCH 07/66] Re-structured Doc --- doc/contributors.md | 4 ++++ doc/convert-data.md | 5 +++++ doc/credits.md | 8 ++++++++ doc/license.md | 7 +++++++ doc/whatsnew.md | 17 +++++++++++++++++ 5 files changed, 41 insertions(+) create mode 100644 doc/contributors.md create mode 100644 doc/convert-data.md create mode 100644 doc/credits.md create mode 100644 doc/license.md create mode 100644 doc/whatsnew.md diff --git a/doc/contributors.md b/doc/contributors.md new file mode 100644 index 0000000000..bca59e445c --- /dev/null +++ b/doc/contributors.md @@ -0,0 +1,4 @@ + +DeePMD-kit contributors +============================== + diff --git a/doc/convert-data.md b/doc/convert-data.md new file mode 100644 index 0000000000..a0c739ad97 --- /dev/null +++ b/doc/convert-data.md @@ -0,0 +1,5 @@ +# Data conversion + +Data conversion, from different fp packages + + diff --git a/doc/credits.md b/doc/credits.md new file mode 100644 index 0000000000..4e88602ac7 --- /dev/null +++ b/doc/credits.md @@ -0,0 +1,8 @@ + +DeePMD Project Coordinators +============================ + + +Core Package Contributors +========================= + diff --git a/doc/license.md b/doc/license.md new file mode 100644 index 0000000000..bb2a602bfb --- /dev/null +++ b/doc/license.md @@ -0,0 +1,7 @@ + +DeePMD-kit License +================== + +The project DeePMD-kit is licensed under GNU LGPLv3.0. + +If you use this code in any future publications, please cite this using 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. diff --git a/doc/whatsnew.md b/doc/whatsnew.md new file mode 100644 index 0000000000..113837e7e4 --- /dev/null +++ b/doc/whatsnew.md @@ -0,0 +1,17 @@ +# What's New +## Type embedding +Instead of training embedding net for each atom pair (regard as G_ij, and turns out to be N^2 networks), we now share a public embedding net (regard as G) and present each atom with a special vector, named as type embedding (v_i). So, our algorithm for generating a description change from G_ij(s_ij) to G(s_ij, v_i, v_j). +1. We obtain the type embedding by a small embedding net, projecting atom type to embedding vector. +2. As for the fitting net, we fix the type embedding and replace individual fitting net with shared fitting net. (while adding type embedding information to its input) + +### Training hyper-parameter +descriptor: +"type" : "se_a_ebd" # for applying share embedding algorithm +"type_filter" : list # network architecture of the small embedding net, which output type embedding +"type_one_side" : bool # when generating descriptor, whether use the centric atom type embedding (true: G(s_ij, v_i, v_j), false: G(s_ij, v_j)) + +fitting_net: +"share_fitting" : bool # if applying share fitting net, set true + + +## Interpolation with tabulated pair potentials From 0a994c26bfbc41c75bb800b57c9d392ad5270e2e Mon Sep 17 00:00:00 2001 From: tuoping Date: Thu, 15 Apr 2021 09:08:32 +0800 Subject: [PATCH 08/66] Re-structured Doc --- doc/api.rst | 2 +- doc/credits.md | 10 ++++++---- doc/license.md | 2 +- 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/doc/api.rst b/doc/api.rst index 07377d37b3..dc857fafb1 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -1,4 +1,4 @@ -DeePMD-kit API +API =============== .. toctree:: diff --git a/doc/credits.md b/doc/credits.md index 4e88602ac7..07b5bb67c4 100644 --- a/doc/credits.md +++ b/doc/credits.md @@ -1,8 +1,10 @@ -DeePMD Project Coordinators -============================ +credits +======= + - [Project Coordinators](#DeePMD-Project-Coordinators) + - [Core Package Contributors](#Core-Package-Contributors) -Core Package Contributors -========================= +# DeePMD Project Coordinators +# Core Package Contributors diff --git a/doc/license.md b/doc/license.md index bb2a602bfb..31cbd0e940 100644 --- a/doc/license.md +++ b/doc/license.md @@ -1,5 +1,5 @@ -DeePMD-kit License +License ================== The project DeePMD-kit is licensed under GNU LGPLv3.0. From 420822c4a9987684ea95b040d9cf146a485bfd55 Mon Sep 17 00:00:00 2001 From: tuoping Date: Thu, 15 Apr 2021 09:22:11 +0800 Subject: [PATCH 09/66] Re-structured Doc --- doc/credits.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/doc/credits.md b/doc/credits.md index 07b5bb67c4..3961768b19 100644 --- a/doc/credits.md +++ b/doc/credits.md @@ -1,10 +1,6 @@ -credits -======= +# credits - - [Project Coordinators](#DeePMD-Project-Coordinators) - - [Core Package Contributors](#Core-Package-Contributors) +## DeePMD Project Coordinators -# DeePMD Project Coordinators - -# Core Package Contributors +## Core Package Contributors From ba1bc7b9f696d4ff9ce07dc4226b672c02165b94 Mon Sep 17 00:00:00 2001 From: tuoping <80671886+tuoping@users.noreply.github.com> Date: Thu, 15 Apr 2021 10:22:24 +0800 Subject: [PATCH 10/66] Set theme jekyll-theme-cayman --- docs/_config.yml | 1 + docs/index.md | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 38 insertions(+) create mode 100644 docs/_config.yml create mode 100644 docs/index.md diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000000..c4192631f2 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1 @@ +theme: jekyll-theme-cayman \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000000..c005dd755d --- /dev/null +++ b/docs/index.md @@ -0,0 +1,37 @@ +## Welcome to GitHub Pages + +You can use the [editor on GitHub](https://github.com/tuoping/deepmd-kit/edit/devel/docs/index.md) to maintain and preview the content for your website in Markdown files. + +Whenever you commit to this repository, GitHub Pages will run [Jekyll](https://jekyllrb.com/) to rebuild the pages in your site, from the content in your Markdown files. + +### Markdown + +Markdown is a lightweight and easy-to-use syntax for styling your writing. It includes conventions for + +```markdown +Syntax highlighted code block + +# Header 1 +## Header 2 +### Header 3 + +- Bulleted +- List + +1. Numbered +2. List + +**Bold** and _Italic_ and `Code` text + +[Link](url) and ![Image](src) +``` + +For more details see [GitHub Flavored Markdown](https://guides.github.com/features/mastering-markdown/). + +### Jekyll Themes + +Your Pages site will use the layout and styles from the Jekyll theme you have selected in your [repository settings](https://github.com/tuoping/deepmd-kit/settings/pages). The name of this theme is saved in the Jekyll `_config.yml` configuration file. + +### Support or Contact + +Having trouble with Pages? Check out our [documentation](https://docs.github.com/categories/github-pages-basics/) or [contact support](https://support.github.com/contact) and we’ll help you sort it out. From dfe2193d3d96c240ad5989c65a6bb0eb1228dad6 Mon Sep 17 00:00:00 2001 From: tuoping <80671886+tuoping@users.noreply.github.com> Date: Thu, 15 Apr 2021 10:23:25 +0800 Subject: [PATCH 11/66] Create index.md From 2c46ffd52806210dd625335f8ea1514c36dd1a77 Mon Sep 17 00:00:00 2001 From: tuoping Date: Thu, 15 Apr 2021 10:40:19 +0800 Subject: [PATCH 12/66] Re-structured Doc --- docs/_config.yml | 1 - docs/index.md | 37 ------------------------------------- 2 files changed, 38 deletions(-) delete mode 100644 docs/_config.yml delete mode 100644 docs/index.md diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index c4192631f2..0000000000 --- a/docs/_config.yml +++ /dev/null @@ -1 +0,0 @@ -theme: jekyll-theme-cayman \ No newline at end of file diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index c005dd755d..0000000000 --- a/docs/index.md +++ /dev/null @@ -1,37 +0,0 @@ -## Welcome to GitHub Pages - -You can use the [editor on GitHub](https://github.com/tuoping/deepmd-kit/edit/devel/docs/index.md) to maintain and preview the content for your website in Markdown files. - -Whenever you commit to this repository, GitHub Pages will run [Jekyll](https://jekyllrb.com/) to rebuild the pages in your site, from the content in your Markdown files. - -### Markdown - -Markdown is a lightweight and easy-to-use syntax for styling your writing. It includes conventions for - -```markdown -Syntax highlighted code block - -# Header 1 -## Header 2 -### Header 3 - -- Bulleted -- List - -1. Numbered -2. List - -**Bold** and _Italic_ and `Code` text - -[Link](url) and ![Image](src) -``` - -For more details see [GitHub Flavored Markdown](https://guides.github.com/features/mastering-markdown/). - -### Jekyll Themes - -Your Pages site will use the layout and styles from the Jekyll theme you have selected in your [repository settings](https://github.com/tuoping/deepmd-kit/settings/pages). The name of this theme is saved in the Jekyll `_config.yml` configuration file. - -### Support or Contact - -Having trouble with Pages? Check out our [documentation](https://docs.github.com/categories/github-pages-basics/) or [contact support](https://support.github.com/contact) and we’ll help you sort it out. From 25cf6879b90e4f1a1df4efe0afedfa271712bacd Mon Sep 17 00:00:00 2001 From: tuoping Date: Thu, 15 Apr 2021 10:49:38 +0800 Subject: [PATCH 13/66] Re-structured Doc --- doc/contributors.md | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 doc/contributors.md diff --git a/doc/contributors.md b/doc/contributors.md deleted file mode 100644 index bca59e445c..0000000000 --- a/doc/contributors.md +++ /dev/null @@ -1,4 +0,0 @@ - -DeePMD-kit contributors -============================== - From 484c9d92169e0a1274877bb9ab857960d63277e5 Mon Sep 17 00:00:00 2001 From: tuoping Date: Fri, 16 Apr 2021 11:52:42 +0800 Subject: [PATCH 14/66] Re-structured index.rst and seperated install.rst into 3 files; Renamed use-deepmd-kit as getting-started, and changed the contents a little. --- doc/api.rst | 62 ++++--- doc/conf.py | 14 +- doc/convert-data.md | 5 - doc/index.rst | 36 +--- doc/install.md | 219 ---------------------- doc/tensorboard.md | 2 +- doc/use-deepmd-kit.md | 417 ------------------------------------------ 7 files changed, 55 insertions(+), 700 deletions(-) delete mode 100644 doc/convert-data.md delete mode 100644 doc/install.md delete mode 100644 doc/use-deepmd-kit.md diff --git a/doc/api.rst b/doc/api.rst index dc857fafb1..ef5260cb3b 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -1,67 +1,83 @@ API -=============== +=== .. toctree:: :maxdepth: 2 :caption: Contents: -.. automodule:: deepmd.Data +.. automodule:: deepmd.utils.data :members: :undoc-members: -.. automodule:: deepmd.DataModifier +.. automodule:: deepmd.infer.dataModifier :members: :undoc-members: -.. automodule:: deepmd.DataSystem +.. automodule:: deepmd.utils.dataSystem :members: :undoc-members: -.. automodule:: deepmd.DeepDipole +.. automodule:: deepmd.descriptor.dipole :members: :undoc-members: -.. automodule:: deepmd.DeepEval +.. automodule:: deepmd.infer.deep_eval :members: :undoc-members: -.. automodule:: deepmd.DeepPolar +.. automodule:: deepmd.infer.deep_polar :members: :undoc-members: -.. automodule:: deepmd.DeepPot +.. automodule:: deepmd.infer.deep_pot :members: :undoc-members: -.. automodule:: deepmd.DeepWFC +.. automodule:: deepmd.infer.deep_wfc :members: :undoc-members: -.. automodule:: deepmd.DescrptLocFrame +.. automodule:: deepmd.descriptor.loc_frame :members: :undoc-members: -.. automodule:: deepmd.DescrptSeA +.. automodule:: deepmd.descriptor.se_a :members: :undoc-members: -.. automodule:: deepmd.DescrptSeAR +.. automodule:: deepmd.descriptor.se_ar :members: :undoc-members: -.. automodule:: deepmd.DescrptSeR +.. automodule:: deepmd.descriptor.se_r :members: :undoc-members: -.. automodule:: deepmd.EwaldRecp +.. automodule:: deepmd.infer.ewald_recp :members: :undoc-members: -.. automodule:: deepmd.Fitting +.. automodule:: deepmd.fit.ener :members: :undoc-members: -.. automodule:: deepmd.LearningRate +.. automodule:: deepmd.fit.dipole + :members: + :undoc-members: + +.. automodule:: deepmd.fit.polar + :members: + :undoc-members: + +.. automodule:: deepmd.fit.wfc + :members: + :undoc-members: + +.. automodule:: deepmd.utils.network + :members: + :undoc-members: + +.. automodule:: deepmd.utils.learning_rate :members: :undoc-members: @@ -69,23 +85,27 @@ API :members: :undoc-members: -.. automodule:: deepmd.Loss +.. automodule:: deepmd.cluster.slurm + :members: + :undoc-members: + +.. automodule:: deepmd.loss.ener :members: :undoc-members: -.. automodule:: deepmd.model +.. automodule:: deepmd.loss.tensor :members: :undoc-members: -.. automodule:: deepmd.Network +.. automodule:: deepmd.model.ener :members: :undoc-members: -.. automodule:: deepmd.TabInter +.. automodule:: deepmd.model.tensor :members: :undoc-members: -.. automodule:: deepmd.trainer +.. automodule:: deepmd.train.trainer :members: :undoc-members: diff --git a/doc/conf.py b/doc/conf.py index 3be81a2de2..e6c4c7d032 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -10,10 +10,10 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - +import os +import sys +sys.path.append(os.path.abspath("..")) +print(sys.path) # -- Project information ----------------------------------------------------- @@ -33,6 +33,7 @@ 'sphinx.ext.autosummary' ] + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -48,10 +49,6 @@ # a list of builtin themes. # html_theme = 'sphinx_rtd_theme' -html_sidebars = { - '**': ['localtoc.html', 'sourcelink.html', 'searchbox.html'], - 'using/windows': ['windowssidebar.html', 'searchbox.html'], -} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -62,3 +59,4 @@ autodoc_default_flags = ['members'] autosummary_generate = True master_doc = 'index' + diff --git a/doc/convert-data.md b/doc/convert-data.md deleted file mode 100644 index a0c739ad97..0000000000 --- a/doc/convert-data.md +++ /dev/null @@ -1,5 +0,0 @@ -# Data conversion - -Data conversion, from different fp packages - - diff --git a/doc/index.rst b/doc/index.rst index d0bbf5402d..9cd2aea5ea 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -3,43 +3,31 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. - +========================== DeePMD-kit's documentation -====================================== +========================== 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. .. Important:: The project DeePMD-kit is licensed under GNU LGPLv3.0. If you use this code in any future publications, please cite this using 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. - .. toctree:: :maxdepth: 2 :caption: User Guide install - use-deepmd-kit + getting-started tensorboard whatsnew - Example Gallery - - - -.. toctree:: - :maxdepth: 2 - :caption: Data Format - - convert-data - - + application-examples + known_issues .. toctree:: :maxdepth: 2 - :caption: I/O Parameters + :caption: Data and Parameters + data-conversion train-input - lammps-pair-style-deepmd - - .. toctree:: :maxdepth: 2 @@ -48,16 +36,6 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r developement api - - -.. toctree:: - :maxdepth: 2 - :caption: Nuts and bolts - - known_issues - - - .. toctree:: :maxdepth: 2 :caption: Project Details diff --git a/doc/install.md b/doc/install.md deleted file mode 100644 index 9cbd1653bb..0000000000 --- a/doc/install.md +++ /dev/null @@ -1,219 +0,0 @@ -- [Easy installation methods](#easy-installation-methods) - - [Offline packages](#offline-packages) - - [With Docker](#with-docker) - - [With conda](#with-conda) -- [From source code](#from-source-code) - - [Install the python interaction](#install-the-python-interface) - - [Install the Tensorflow's python interface](#install-the-tensorflows-python-interface) - - [Install the DeePMD-kit's python interface](#install-the-deepmd-kits-python-interface) - - [Install the C++ interface](#install-the-c-interface) - - [Install the Tensorflow's C++ interface](#install-the-tensorflows-c-interface) - - [Install the DeePMD-kit's C++ interface](#install-the-deepmd-kits-c-interface) - - [Install LAMMPS's DeePMD-kit module](#install-lammpss-deepmd-kit-module) - - [Hardware platforms](#hardware-platforms) - - -# Easy installation methods -There various easy methods to install DeePMD-kit. Choose one that you prefer. If you want to build by yourself, jump to the next two sections. - -After your easy installation, DeePMD-kit (`dp`) and LAMMPS (`lmp`) will be available to execute. You can try `dp -h` and `lmp -h` to see the help. `mpirun` is also available considering you may want to run LAMMPS in parallel. - -## Offline packages -Both CPU and GPU version offline packages are avaiable in [the Releases page](https://github.com/deepmodeling/deepmd-kit/releases). - -## With conda -DeePMD-kit is avaiable with [conda](https://github.com/conda/conda). Install [Anaconda](https://www.anaconda.com/distribution/#download-section) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html) first. - -To install the CPU version: -```bash -conda install deepmd-kit=*=*cpu lammps-dp=*=*cpu -c deepmodeling -``` - -To install the GPU version containing [CUDA 10.1](https://docs.nvidia.com/deploy/cuda-compatibility/index.html#binary-compatibility__table-toolkit-driver): -```bash -conda install deepmd-kit=*=*gpu lammps-dp=*=*gpu -c deepmodeling -``` - -## With Docker -A docker for installing the DeePMD-kit is available [here](https://github.com/orgs/deepmodeling/packages/container/package/deepmd-kit). - -To pull the CPU version: -```bash -docker pull ghcr.io/deepmodeling/deepmd-kit:1.3.1_cpu -``` - -To pull the GPU version: -```bash -docker pull ghcr.io/deepmodeling/deepmd-kit:1.3.1_cuda10.1_gpu -``` - - -# From source code - -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 --recursive https://github.com/deepmodeling/deepmd-kit.git deepmd-kit -``` -The `--recursive` option clones all [submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) needed by DeePMD-kit. - -For convenience, you may want to record the location of source to a variable, saying `deepmd_source_dir` by -```bash -cd deepmd-kit -deepmd_source_dir=`pwd` -``` - - -## Install the python interface -### Install the Tensorflow's python interface -First, check the python version on your machine -```bash -python --version -``` - -We follow the virtual environment approach to install the tensorflow's Python interface. The full instruction can be found on [the tensorflow's official website](https://www.tensorflow.org/install/pip). Now we assume that the Python interface will be installed to virtual environment directory `$tensorflow_venv` -```bash -virtualenv -p python3 $tensorflow_venv -source $tensorflow_venv/bin/activate -pip install --upgrade pip -pip install --upgrade tensorflow==2.3.0 -``` -It is notice that everytime a new shell is started and one wants to use `DeePMD-kit`, the virtual environment should be activated by -```bash -source $tensorflow_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 like python3.x, it can be specified by, for example -```bash -virtualenv -p python3.7 $tensorflow_venv -``` -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==2.3.0 -``` -To verify the installation, run -```bash -python -c "import tensorflow as tf;print(tf.reduce_sum(tf.random.normal([1000, 1000])))" -``` -One should remember to activate the virtual environment every time he/she uses deepmd-kit. - -### Install the DeePMD-kit's python interface - -Execute -```bash -cd $deepmd_source_dir -pip install . -``` -To test the installation, one should firstly 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} ... - -DeePMD-kit: A deep learning package for many-body potential energy -representation and molecular dynamics - -optional arguments: - -h, --help show this help message and exit - -Valid subcommands: - {train,freeze,test} - train train a model - freeze freeze the model - test test the model -``` - -## Install the C++ interface - -If one does not need to use DeePMD-kit with Lammps or I-Pi, then the python interface installed in the previous section does everything and he/she can safely skip this section. - -### Install the Tensorflow's C++ interface - -Check the compiler version on your machine - -``` -gcc --version -``` - -The C++ interface of DeePMD-kit was tested with compiler gcc >= 4.8. It is noticed that the I-Pi support is only compiled with gcc >= 4.9. - -First the C++ interface of Tensorflow should be installed. It is noted that the version of Tensorflow should be in consistent with the python interface. You may follow [the instruction](install-tf.2.3.md) to install the corresponding C++ interface. - -### Install the DeePMD-kit's C++ interface - -Now goto the source code directory of DeePMD-kit and make a build place. -```bash -cd $deepmd_source_dir/source -mkdir build -cd build -``` -I assume you want to install DeePMD-kit into path `$deepmd_root`, then execute cmake -```bash -cmake -DTENSORFLOW_ROOT=$tensorflow_root -DCMAKE_INSTALL_PREFIX=$deepmd_root .. -``` -where the variable `tensorflow_root` stores the location where the tensorflow's C++ interface is installed. The DeePMD-kit will automatically detect if a CUDA tool-kit is available on your machine and build the GPU support accordingly. If you want to force the cmake to find CUDA tool-kit, you can speicify the key `USE_CUDA_TOOLKIT`, -```bash -cmake -DUSE_CUDA_TOOLKIT=true -DTENSORFLOW_ROOT=$tensorflow_root -DCMAKE_INSTALL_PREFIX=$deepmd_root .. -``` -and you may further asked to provide `CUDA_TOOLKIT_ROOT_DIR`. If the cmake has executed successfully, then -```bash -make -make install -``` -If everything works fine, you will have the following executable and libraries installed in `$deepmd_root/bin` and `$deepmd_root/lib` -```bash -$ ls $deepmd_root/bin -dp_ipi -$ ls $deepmd_root/lib -libdeepmd_ipi.so libdeepmd_op.so libdeepmd.so -``` - -### Install LAMMPS's DeePMD-kit module -DeePMD-kit provide module for running MD simulation with LAMMPS. Now make the DeePMD-kit module for LAMMPS. -```bash -cd $deepmd_source_dir/source/build -make lammps -``` -DeePMD-kit will generate a module called `USER-DEEPMD` in the `build` directory. Now download the LAMMPS code (`29Oct2020` or later), and uncompress it: -```bash -cd /some/workspace -wget https://github.com/lammps/lammps/archive/stable_29Oct2020.tar.gz -tar xf stable_29Oct2020.tar.gz -``` -The source code of LAMMPS is stored in directory `lammps-stable_29Oct2020`. Now go into the LAMMPS code and copy the DeePMD-kit module like this -```bash -cd lammps-stable_29Oct2020/src/ -cp -r $deepmd_source_dir/source/build/USER-DEEPMD . -``` -Now build LAMMPS -```bash -make yes-kspace -make yes-user-deepmd -make mpi -j4 -``` -The 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 end up with an executable `lmp_mpi`. -```bash -./lmp_mpi -h -``` - -The DeePMD-kit module can be removed from LAMMPS source code by -```bash -make no-user-deepmd -``` - -## Hardware platforms - - diff --git a/doc/tensorboard.md b/doc/tensorboard.md index fdc2b00760..826648c9b6 100644 --- a/doc/tensorboard.md +++ b/doc/tensorboard.md @@ -1,4 +1,4 @@ -# DeePMD-kit TensorBoard usage +# TensorBoard usage TensorBoard provides the visualization and tooling needed for machine learning experimentation. A full instruction of tensorboard can be found diff --git a/doc/use-deepmd-kit.md b/doc/use-deepmd-kit.md deleted file mode 100644 index e456137578..0000000000 --- a/doc/use-deepmd-kit.md +++ /dev/null @@ -1,417 +0,0 @@ -- [Use DeePMD-kit](#use-deepmd-kit) - - [Prepare data](#prepare-data) - - [Train a model](#train-a-model) - - [The DeePMD model](#the-deepmd-model) - - [The DeepPot-SE model](#the-deeppot-se-model) - - [Freeze a model](#freeze-a-model) - - [Test a model](#test-a-model) - - [Compress a model](#compress-a-model) - - [Model inference](#model-inference) - - [Run MD with Lammps](#run-md-with-lammps) - - [Include deepmd in the pair style](#include-deepmd-in-the-pair-style) - - [Long-range interaction](#long-range-interaction) - - [Run path-integral MD with i-PI](#run-path-integral-md-with-i-pi) - - [Use deep potential with ASE](#use-deep-potential-with-ase) - -# Use DeePMD-kit -In this text, we will call the deep neural network that is used to represent the interatomic interactions (Deep Potential) the **model**. The typical procedure of using DeePMD-kit is - -1. Prepare data -2. Train a model -3. Freeze the model -4. Test the model -5. Compress the model -6. Inference with the model - -## Prepare data -One needs to provide the following information to train a model: the atom type, the simulation box, the atom coordinate, the atom force, system energy and virial. A snapshot of a system that contains these information is called a **frame**. We use the following convention of units: - -Property| Unit ---- | :---: -Time | ps -Length | Å -Energy | eV -Force | eV/Å -Virial | eV -Pressure| Bar - -The frames of the system are stored in two formats. A raw file is a plain text file with each information item written in one file and one frame written on one line. The default files that provide box, coordinate, force, energy and virial are `box.raw`, `coord.raw`, `force.raw`, `energy.raw` and `virial.raw`, respectively. *We recommend you use these file names*. 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. The coordinate file `coord.raw` is organized similarly. In `box.raw`, the 9 components of the box vectors should be provided on each line. In `virial.raw`, the 9 components of the virial tensor should be provided on each line in the order `XX XY XZ YX YY YZ ZX ZY ZZ`. The number of lines of all raw files should be identical. - -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 -``` - -The second format is the data sets of `numpy` binary data that are directly used by the training program. User can use the script `$deepmd_source_dir/data/raw/raw_to_set.sh` to convert the prepared raw files to data sets. 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 -$ $deepmd_source_dir/data/raw/raw_to_set.sh 2000 -nframe is 6000 -nline per set is 2000 -will make 3 sets -making set 0 ... -making set 1 ... -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 contains 2000 frames. The last set (`set.002`) is used as testing set, while the rest sets (`set.000` and `set.001`) are used as training sets. One do not need to take care of the binary data files in each of the `set.*` directories. The path containing `set.*` and `type.raw` is called a *system*. - -## Train a model - -### Write the input script - -The method of training is explained in our [DeePMD][2] and [DeepPot-SE][3] papers. With the source code we provide a small training dataset taken from 400 frames generated by NVT ab-initio water MD trajectory with 300 frames for training and 100 for testing. [An example training parameter file](./examples/water/train/water_se_a.json) is provided. One can try with the training by -```bash -$ cd $deepmd_source_dir/examples/water/train/ -$ dp train water_se_a.json -``` -where `water_se_a.json` is the `json` format parameter file that controls the training. It is also possible to use `yaml` format file with the same keys as json (see `water_se_a.yaml` example). You can use script `json2yaml.py` in `data/json/` dir to convert your json files to yaml. The components of the `water.json` contains four parts, `model`, `learning_rate`, `loss` and `training`. - -The `model` section specify how the deep potential model is built. An example of the smooth-edition is provided as follows -```json - "model": { - "type_map": ["O", "H"], - "descriptor" :{ - "type": "se_a", - "rcut_smth": 5.80, - "rcut": 6.00, - "sel": [46, 92], - "neuron": [25, 50, 100], - "axis_neuron": 16, - "resnet_dt": false, - "seed": 1, - "_comment": " that's all" - }, - "fitting_net" : { - "neuron": [240, 240, 240], - "resnet_dt": true, - "seed": 1, - "_comment": " that's all" - }, - "_comment": " that's all" - } -``` -The **`type_map`** is optional, which provide the element names (but not restricted to) for corresponding atom types. - -The construction of the descriptor is given by option **`descriptor`**. The **`type`** of the descriptor is set to `"se_a"`, which means smooth-edition, angular infomation. The **`rcut`** is the cut-off radius for neighbor searching, and the **`rcut_smth`** gives where the smoothing starts. **`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]` denote the maximum possible number of neighbors with type `i`. The **`neuron`** specifies the size of the embedding net. From left to right the members denote the sizes of each hidden layers from input end to the output end, respectively. The **`axis_neuron`** specifies the size of submatrix of the embedding matrix, the axis matrix as explained in the [DeepPot-SE paper][3]. If the outer layer is of twice size as the inner layer, then the inner layer is copied and concatenated, then a [ResNet architecture](https://arxiv.org/abs/1512.03385) is build between them. If the option **`resnet_dt`** is set `true`, then a timestep is used in the ResNet. **`seed`** gives the random seed that is used to generate random numbers when initializing the model parameters. - -The construction of the fitting net is give by **`fitting_net`**. The key **`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 build between them. If the option **`resnet_dt`** is set `true`, then a timestep is used in the ResNet. **`seed`** gives the random seed that is used to generate random numbers when initializing the model parameters. - -An example of the `learning_rate` is given as follows -```json - "learning_rate" :{ - "type": "exp", - "start_lr": 0.005, - "decay_steps": 5000, - "decay_rate": 0.95, - "_comment": "that's all" - } -``` -The option **`start_lr`**, **`decay_rate`** and **`decay_steps`** specify how the learning rate changes. For example, the `t`th batch will be trained with learning rate: -```math -lr(t) = start_lr * decay_rate ^ ( t / decay_steps ) -``` - -An example of the `loss` is -```json - "loss" : { - "start_pref_e": 0.02, - "limit_pref_e": 1, - "start_pref_f": 1000, - "limit_pref_f": 1, - "start_pref_v": 0, - "limit_pref_v": 0, - "_comment": " that's all" - } -``` -The options **`start_pref_e`**, **`limit_pref_e`**, **`start_pref_f`**, **`limit_pref_f`**, **`start_pref_v`** and **`limit_pref_v`** determine how the prefactors of energy error, force error and virial error changes in the loss function (see the appendix of the [DeePMD paper][2] for details). Taking the prefactor of force error for example, the prefactor at batch `t` is -```math -w_f(t) = start_pref_f * ( lr(t) / start_lr ) + limit_pref_f * ( 1 - lr(t) / start_lr ) -``` -Since we do not have virial data, the virial prefactors `start_pref_v` and `limit_pref_v` are set to 0. - -An example of `training` is -```json - "training" : { - "systems": ["../data1/", "../data2/"], - "set_prefix": "set", - "stop_batch": 1000000, - "_comment": " batch_size can be supplied with, e.g. 1, or auto (string) or [10, 20]", - "batch_size": 1, - - "seed": 1, - - "_comment": " display and restart", - "_comment": " frequencies counted in batch", - "disp_file": "lcurve.out", - "disp_freq": 100, - "_comment": " numb_test can be supplied with, e.g. 1, or XX% (string) or [10, 20]", - "numb_test": 10, - "save_freq": 1000, - "save_ckpt": "model.ckpt", - "load_ckpt": "model.ckpt", - "disp_training":true, - "time_training":true, - "profiling": false, - "profiling_file":"timeline.json", - "_comment": "that's all" - } -``` -The option **`systems`** provide location of the systems (path to `set.*` and `type.raw`). It is a vector, thus DeePMD-kit allows you to provide multiple systems. DeePMD-kit will train the model with the systems in the vector one by one in a cyclic manner. **It is warned that the example water data (in folder `examples/data/water`) is of very limited amount, is provided only for testing purpose, and should not be used to train a productive model.** - -The option **`batch_size`** specifies the number of frames in each batch. It can be set to `"auto"` to enable a automatic batch size or it can be input as a list setting batch size individually for each system. -The option **`stop_batch`** specifies the total number of batches will be used in the training. - -The option **`numb_test`** specifies the number of tests that will be used for each system. If it is an integer each system will be tested with the same number of tests. It can be set to percentage `"XX%"` to use XX% of frames of each system for its testing or it can be input as a list setting numer of tests individually for each system (the order should correspond to ordering of the systems key in json). - -### Training - -The training can be invoked by -```bash -$ dp train water_se_a.json -``` - -During the training, the error of the model is tested every **`disp_freq`** batches with **`numb_test`** frames from the last set in the **`systems`** directory on the fly, and the results are output to **`disp_file`**. A typical `disp_file` looks like -```bash -# batch l2_tst l2_trn l2_e_tst l2_e_trn l2_f_tst l2_f_trn lr - 0 2.67e+01 2.57e+01 2.21e-01 2.22e-01 8.44e-01 8.12e-01 1.0e-03 - 100 6.14e+00 5.40e+00 3.01e-01 2.99e-01 1.93e-01 1.70e-01 1.0e-03 - 200 5.02e+00 4.49e+00 1.53e-01 1.53e-01 1.58e-01 1.42e-01 1.0e-03 - 300 4.36e+00 3.71e+00 7.32e-02 7.27e-02 1.38e-01 1.17e-01 1.0e-03 - 400 4.04e+00 3.29e+00 3.16e-02 3.22e-02 1.28e-01 1.04e-01 1.0e-03 -``` -The first column displays the number of batches. The second and third columns display the loss function evaluated by `numb_test` frames randomly chosen from the test set and that evaluated by the current training batch, respectively. The fourth and fifth columns display the RMS energy error (normalized by number of atoms) evaluated by `numb_test` frames randomly chosen from the test set and that evaluated by the current training batch, respectively. The sixth and seventh columns display the RMS force error (component-wise) evaluated by `numb_test` frames randomly chosen from the test set and that evaluated by the current training batch, respectively. The last column displays the current learning rate. - -Checkpoints will be written to files with prefix **`save_ckpt`** every **`save_freq`** batches. If **`restart`** is set to `true`, then the training will start from the checkpoint named **`load_ckpt`**, rather than from scratch. - -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 - -optional arguments: - -h, --help show this help message and exit - --init-model INIT_MODEL - Initialize a model by the provided checkpoint - --restart RESTART Restart the training from the provided checkpoint -``` -The keys `intra_op_parallelism_threads` and `inter_op_parallelism_threads` are Tensorflow configurations for multithreading, which are explained [here](https://www.tensorflow.org/performance/performance_guide#optimizing_for_cpu). Skipping `-t` and `OMP_NUM_THREADS` leads to the default setting of these keys in the Tensorflow. - -**`--init-model model.ckpt`**, for example, initializes the model training with an existing model that is stored in the checkpoint `model.ckpt`, the network architectures should match. - -**`--restart model.ckpt`**, continues the training from the checkpoint `model.ckpt`. - -On some resources limited machines, one may want to control the number of threads used by DeePMD-kit. This is achieved by three environmental variables: `OMP_NUM_THREADS`, `TF_INTRA_OP_PARALLELISM_THREADS` and `TF_INTER_OP_PARALLELISM_THREADS`. `OMP_NUM_THREADS` controls the multithreading of DeePMD-kit implemented operations. `TF_INTRA_OP_PARALLELISM_THREADS` and `TF_INTER_OP_PARALLELISM_THREADS` controls `intra_op_parallelism_threads` and `inter_op_parallelism_threads`, which are Tensorflow configurations for multithreading. An explanation is found [here](https://stackoverflow.com/questions/41233635/meaning-of-inter-op-parallelism-threads-and-intra-op-parallelism-threads). - -For example if you wish to use 3 cores of 2 CPUs on one node, you may set the environmental variables and run DeePMD-kit as follows: -```bash -export OMP_NUM_THREADS=6 -export TF_INTRA_OP_PARALLELISM_THREADS=3 -export TF_INTER_OP_PARALLELISM_THREADS=2 -dp train input.json -``` - -### Training analysis with Tensorboard - -If enbled in json/yaml input file DeePMD-kit will create log files which can be -used to analyze training procedure with Tensorboard. For a short tutorial -please read this [document](doc/tensorboard.md). - -## Freeze a model - -The trained neural network is extracted from a checkpoint and dumped into a database. This process is called "freezing" a model. The idea and part of our code are from [Morgan](https://blog.metaflow.fr/tensorflow-how-to-freeze-a-model-and-serve-it-with-a-python-api-d4f3596b3adc). To freeze a model, typically one does -```bash -$ dp freeze -o graph.pb -``` -in the folder where the model is trained. The output database is called `graph.pb`. - - -## 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] - -optional arguments: - -h, --help show this help message and exit - -m MODEL, --model MODEL - Frozen model file to import - -s SYSTEM, --system SYSTEM - The system dir - -S SET_PREFIX, --set-prefix SET_PREFIX - The set prefix - -n NUMB_TEST, --numb-test NUMB_TEST - The number of data for test - -r RAND_SEED, --rand-seed RAND_SEED - The random seed - --shuffle-test Shuffle test data - -d DETAIL_FILE, --detail-file DETAIL_FILE - The file containing details of energy force and virial - accuracy -``` - -## Compress a model - -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 input.json -i graph.pb -o graph-compress.pb -``` -where input.json denotes the original training input script, `-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] [-i INPUT] [-o OUTPUT] [-e EXTRAPOLATE] [-s STRIDE] - [-f FREQUENCY] [-d FOLDER] - INPUT - -positional arguments: - INPUT The input parameter file in json or yaml format, which - should be consistent with the original model parameter - file - -optional arguments: - -h, --help show this help message and exit - -i INPUT, --input INPUT - The original frozen model, which will be compressed by - the deepmd-kit - -o OUTPUT, --output OUTPUT - The compressed model - -e EXTRAPOLATE, --extrapolate EXTRAPOLATE - The scale of model extrapolation - -s STRIDE, --stride STRIDE - The uniform stride of tabulation's first table, the - second table will use 10 * stride as it's uniform - stride - -f FREQUENCY, --frequency FREQUENCY - The frequency of tabulation overflow check(If the - input environment matrix overflow the first or second - table range). By default do not check the overflow - -d FOLDER, --folder FOLDER - path to checkpoint folder -``` -**Parameter explanation** - -Model compression, which including tabulating the embedding-net. -The table is composed of fifth-order polynomial coefficients and is assembled from two sub-tables. The first sub-table takes the stride(parameter) as it's uniform stride, while the second sub-table takes 10 * 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 overflow the first or second table range) during the MD inference. - -**Justification of model compression** - -Model compression, with little loss of accuracy, can greatly speed up MD inference time. According to different simulation systems and training parameters, the speedup can reach more than 10 times at both CPU and GPU devices. At the same time, model compression can greatly change the memory usage, reducing as much as 20 times under the same hardware conditions. - -**Acceptable original model version** - -The model compression method requires that the version of DeePMD-kit used in original model generation should be 1.3 or above. If one has a frozen 1.2 model, one can first use the convenient conversion interface of DeePMD-kit-v1.2.4 to get a 1.3 executable model.(eg: ```dp convert-to-1.3 -i frozen_1.2.pb -o frozen_1.3.pb```) - -## Model inference -One may use the python interface of DeePMD-kit for model inference, an example is given as follows -```python -from deepmd import DeepPot -import numpy as np -dp = DeepPot('graph.pb') -coord = np.array([[1,0,0], [0,0,1.5], [1,0,3]]).reshape([1, -1]) -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. - - -## Run MD with LAMMPS -### Include deepmd in the pair style -Running an MD simulation with LAMMPS is simpler. In the LAMMPS input file, one needs to specify the pair style as follows -```bash -pair_style deepmd graph.pb -pair_coeff -``` -where `graph.pb` is the file name of the frozen model. The `pair_coeff` should be left blank. It should be noted that LAMMPS counts atom types starting from 1, therefore, all LAMMPS atom type will be firstly subtracted by 1, and then passed into the DeePMD-kit engine to compute the interactions. [A detailed documentation of this pair style is available.](doc/lammps-pair-style-deepmd.md). - -### 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 -```bash -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. - -## 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, force and virial). The server and client communicates via the Unix domain socket or the Internet socket. The client can be started by -```bash -$ dp_ipi water.json -``` -It is noted that multiple instances of the client is allow for computing, in parallel, the interactions of multiple replica of the path-integral MD. - -`water.json` is the parameter file for the client `dp_ipi`, and [an example](./examples/ipi/water.json) 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 - } -} -``` -The option **`use_unix`** is set to `true` to activate the Unix domain socket, otherwise, the Internet socket is used. - -The option **`graph_file`** provides the file name of the frozen model. - -The `dp_ipi` gets the atom names from an [XYZ file](https://en.wikipedia.org/wiki/XYZ_file_format) provided by **`coord_file`** (meanwhile ignores all coordinates in it), and translates the names to atom types by rules provided by **`atom_type`**. - -## 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 - -water = Atoms('H2O', - positions=[(0.7601, 1.9270, 1), - (1.9575, 1, 1), - (1., 1., 1.)], - cell=[100, 100, 100], - calculator=DP(model="frozen_model.pb")) -print(water.get_potential_energy()) -print(water.get_forces()) -``` - -Optimization is also available: -```python -from ase.optimize import BFGS -dyn = BFGS(water) -dyn.run(fmax=1e-6) -print(water.get_positions()) -``` From 1a556470faa2a017b37e732993e86dc2f0904095 Mon Sep 17 00:00:00 2001 From: tuoping Date: Fri, 16 Apr 2021 11:56:55 +0800 Subject: [PATCH 15/66] Same as before --- doc/data-conversion.md | 5 + doc/getting-started.md | 455 ++++++++++++++++++++++++++++++ doc/install.rst | 10 + doc/install_easy.md | 39 +++ doc/install_hardware-platforms.md | 3 + doc/install_off-line-packages.md | 4 + doc/install_source.md | 173 ++++++++++++ doc/install_with-conda.md | 12 + doc/known_issues.md | 1 + 9 files changed, 702 insertions(+) create mode 100644 doc/data-conversion.md create mode 100644 doc/getting-started.md create mode 100644 doc/install.rst create mode 100644 doc/install_easy.md create mode 100644 doc/install_hardware-platforms.md create mode 100644 doc/install_off-line-packages.md create mode 100644 doc/install_source.md create mode 100644 doc/install_with-conda.md create mode 100644 doc/known_issues.md diff --git a/doc/data-conversion.md b/doc/data-conversion.md new file mode 100644 index 0000000000..a0c739ad97 --- /dev/null +++ b/doc/data-conversion.md @@ -0,0 +1,5 @@ +# Data conversion + +Data conversion, from different fp packages + + diff --git a/doc/getting-started.md b/doc/getting-started.md new file mode 100644 index 0000000000..80442897c9 --- /dev/null +++ b/doc/getting-started.md @@ -0,0 +1,455 @@ +# Getting started +In this text, we will call the deep neural network that is used to represent the interatomic interactions (Deep Potential) the **model**. The typical procedure of using DeePMD-kit is + +1. [Prepare data](#prepare-data) +2. [Train a model](#train-a-model) + - [The DeePMD model](#the-deepmd-model) + - [The DeepPot-SE model](#the-deeppot-se-model) +3. [Freeze a model](#freeze-a-model) +4. [Test a model](#test-a-model) +5. [Compress a model](#compress-a-model) +6. [Model inference](#model-inference) +7. [Run MD](#run-md) + - [Run MD with LAMMPS](#Run-MD-with-LAMMPS) + - [Run path-integral MD with i-PI](#run-path-integral-md-with-i-pi) + - [Use deep potential with ASE](#use-deep-potential-with-ase) + + +## Prepare data +One needs to provide the following information to train a model: the atom type, the simulation box, the atom coordinate, the atom force, system energy and virial. A snapshot of a system that contains these information is called a **frame**. We use the following convention of units: + +Property| Unit +--- | :---: +Time | ps +Length | Å +Energy | eV +Force | eV/Å +Virial | eV +Pressure| Bar + +The frames of the system are stored in two formats. A raw file is a plain text file with each information item written in one file and one frame written on one line. The default files that provide box, coordinate, force, energy and virial are `box.raw`, `coord.raw`, `force.raw`, `energy.raw` and `virial.raw`, respectively. *We recommend you use these file names*. 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. The coordinate file `coord.raw` is organized similarly. In `box.raw`, the 9 components of the box vectors should be provided on each line. In `virial.raw`, the 9 components of the virial tensor should be provided on each line in the order `XX XY XZ YX YY YZ ZX ZY ZZ`. The number of lines of all raw files should be identical. + +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 +``` + +The second format is the data sets of `numpy` binary data that are directly used by the training program. User can use the script `$deepmd_source_dir/data/raw/raw_to_set.sh` to convert the prepared raw files to data sets. 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 +$ $deepmd_source_dir/data/raw/raw_to_set.sh 2000 +nframe is 6000 +nline per set is 2000 +will make 3 sets +making set 0 ... +making set 1 ... +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 contains 2000 frames. The last set (`set.002`) is used as testing set, while the rest sets (`set.000` and `set.001`) are used as training sets. One do not need to take care of the binary data files in each of the `set.*` directories. The path containing `set.*` and `type.raw` is called a *system*. + +## Train a model + +### Write the input script + +The method of training is explained in our [DeePMD][2] and [DeepPot-SE][3] papers. With the source code we provide a small training dataset taken from 400 frames generated by NVT ab-initio water MD trajectory with 300 frames for training and 100 for testing. [An example training parameter file](./examples/water/train/water_se_a.json) is provided. One can try with the training by +```bash +$ cd $deepmd_source_dir/examples/water/train/ +$ dp train water_se_a.json +``` +where `water_se_a.json` is the `json` format parameter file that controls the training. It is also possible to use `yaml` format file with the same keys as json (see `water_se_a.yaml` example). You can use script `json2yaml.py` in `data/json/` dir to convert your json files to yaml. The components of the `water.json` contains four parts, `model`, `learning_rate`, `loss` and `training`. + +The `model` section specify how the deep potential model is built. An example of the smooth-edition is provided as follows +```json + "model": { + "type_map": ["O", "H"], + "descriptor" :{ + "type": "se_a", + "rcut_smth": 5.80, + "rcut": 6.00, + "sel": [46, 92], + "neuron": [25, 50, 100], + "axis_neuron": 16, + "resnet_dt": false, + "seed": 1, + "_comment": " that's all" + }, + "fitting_net" : { + "neuron": [240, 240, 240], + "resnet_dt": true, + "seed": 1, + "_comment": " that's all" + }, + "_comment": " that's all" + } +``` +The **`type_map`** is optional, which provide the element names (but not restricted to) for corresponding atom types. + +The construction of the descriptor is given by option **`descriptor`**. The **`type`** of the descriptor is set to `"se_a"`, which means smooth-edition, angular infomation. The **`rcut`** is the cut-off radius for neighbor searching, and the **`rcut_smth`** gives where the smoothing starts. **`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]` denote the maximum possible number of neighbors with type `i`. The **`neuron`** specifies the size of the embedding net. From left to right the members denote the sizes of each hidden layers from input end to the output end, respectively. The **`axis_neuron`** specifies the size of submatrix of the embedding matrix, the axis matrix as explained in the [DeepPot-SE paper][3]. If the outer layer is of twice size as the inner layer, then the inner layer is copied and concatenated, then a [ResNet architecture](https://arxiv.org/abs/1512.03385) is build between them. If the option **`resnet_dt`** is set `true`, then a timestep is used in the ResNet. **`seed`** gives the random seed that is used to generate random numbers when initializing the model parameters. + +The construction of the fitting net is give by **`fitting_net`**. The key **`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 build between them. If the option **`resnet_dt`** is set `true`, then a timestep is used in the ResNet. **`seed`** gives the random seed that is used to generate random numbers when initializing the model parameters. + +An example of the `learning_rate` is given as follows +```json + "learning_rate" :{ + "type": "exp", + "start_lr": 0.005, + "decay_steps": 5000, + "decay_rate": 0.95, + "_comment": "that's all" + } +``` +The option **`start_lr`**, **`decay_rate`** and **`decay_steps`** specify how the learning rate changes. For example, the `t`th batch will be trained with learning rate: +```math +lr(t) = start_lr * decay_rate ^ ( t / decay_steps ) +``` + +An example of the `loss` is +```json + "loss" : { + "start_pref_e": 0.02, + "limit_pref_e": 1, + "start_pref_f": 1000, + "limit_pref_f": 1, + "start_pref_v": 0, + "limit_pref_v": 0, + "_comment": " that's all" + } +``` +The options **`start_pref_e`**, **`limit_pref_e`**, **`start_pref_f`**, **`limit_pref_f`**, **`start_pref_v`** and **`limit_pref_v`** determine how the prefactors of energy error, force error and virial error changes in the loss function (see the appendix of the [DeePMD paper][2] for details). Taking the prefactor of force error for example, the prefactor at batch `t` is +```math +w_f(t) = start_pref_f * ( lr(t) / start_lr ) + limit_pref_f * ( 1 - lr(t) / start_lr ) +``` +Since we do not have virial data, the virial prefactors `start_pref_v` and `limit_pref_v` are set to 0. + +An example of `training` is +```json + "training" : { + "systems": ["../data1/", "../data2/"], + "set_prefix": "set", + "stop_batch": 1000000, + "_comment": " batch_size can be supplied with, e.g. 1, or auto (string) or [10, 20]", + "batch_size": 1, + + "seed": 1, + + "_comment": " display and restart", + "_comment": " frequencies counted in batch", + "disp_file": "lcurve.out", + "disp_freq": 100, + "_comment": " numb_test can be supplied with, e.g. 1, or XX% (string) or [10, 20]", + "numb_test": 10, + "save_freq": 1000, + "save_ckpt": "model.ckpt", + "load_ckpt": "model.ckpt", + "disp_training":true, + "time_training":true, + "profiling": false, + "profiling_file":"timeline.json", + "_comment": "that's all" + } +``` +The option **`systems`** provide location of the systems (path to `set.*` and `type.raw`). It is a vector, thus DeePMD-kit allows you to provide multiple systems. DeePMD-kit will train the model with the systems in the vector one by one in a cyclic manner. **It is warned that the example water data (in folder `examples/data/water`) is of very limited amount, is provided only for testing purpose, and should not be used to train a productive model.** + +The option **`batch_size`** specifies the number of frames in each batch. It can be set to `"auto"` to enable a automatic batch size or it can be input as a list setting batch size individually for each system. +The option **`stop_batch`** specifies the total number of batches will be used in the training. + +The option **`numb_test`** specifies the number of tests that will be used for each system. If it is an integer each system will be tested with the same number of tests. It can be set to percentage `"XX%"` to use XX% of frames of each system for its testing or it can be input as a list setting numer of tests individually for each system (the order should correspond to ordering of the systems key in json). + +### Training + +The training can be invoked by +```bash +$ dp train water_se_a.json +``` + +During the training, the error of the model is tested every **`disp_freq`** batches with **`numb_test`** frames from the last set in the **`systems`** directory on the fly, and the results are output to **`disp_file`**. A typical `disp_file` looks like +```bash +# batch l2_tst l2_trn l2_e_tst l2_e_trn l2_f_tst l2_f_trn lr + 0 2.67e+01 2.57e+01 2.21e-01 2.22e-01 8.44e-01 8.12e-01 1.0e-03 + 100 6.14e+00 5.40e+00 3.01e-01 2.99e-01 1.93e-01 1.70e-01 1.0e-03 + 200 5.02e+00 4.49e+00 1.53e-01 1.53e-01 1.58e-01 1.42e-01 1.0e-03 + 300 4.36e+00 3.71e+00 7.32e-02 7.27e-02 1.38e-01 1.17e-01 1.0e-03 + 400 4.04e+00 3.29e+00 3.16e-02 3.22e-02 1.28e-01 1.04e-01 1.0e-03 +``` +The first column displays the number of batches. The second and third columns display the loss function evaluated by `numb_test` frames randomly chosen from the test set and that evaluated by the current training batch, respectively. The fourth and fifth columns display the RMS energy error (normalized by number of atoms) evaluated by `numb_test` frames randomly chosen from the test set and that evaluated by the current training batch, respectively. The sixth and seventh columns display the RMS force error (component-wise) evaluated by `numb_test` frames randomly chosen from the test set and that evaluated by the current training batch, respectively. The last column displays the current learning rate. + +Checkpoints will be written to files with prefix **`save_ckpt`** every **`save_freq`** batches. If **`restart`** is set to `true`, then the training will start from the checkpoint named **`load_ckpt`**, rather than from scratch. + +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 + +optional arguments: + -h, --help show this help message and exit + --init-model INIT_MODEL + Initialize a model by the provided checkpoint + --restart RESTART Restart the training from the provided checkpoint +``` +The keys `intra_op_parallelism_threads` and `inter_op_parallelism_threads` are Tensorflow configurations for multithreading, which are explained [here](https://www.tensorflow.org/performance/performance_guide#optimizing_for_cpu). Skipping `-t` and `OMP_NUM_THREADS` leads to the default setting of these keys in the Tensorflow. + +**`--init-model model.ckpt`**, for example, initializes the model training with an existing model that is stored in the checkpoint `model.ckpt`, the network architectures should match. + +**`--restart model.ckpt`**, continues the training from the checkpoint `model.ckpt`. + +On some resources limited machines, one may want to control the number of threads used by DeePMD-kit. This is achieved by three environmental variables: `OMP_NUM_THREADS`, `TF_INTRA_OP_PARALLELISM_THREADS` and `TF_INTER_OP_PARALLELISM_THREADS`. `OMP_NUM_THREADS` controls the multithreading of DeePMD-kit implemented operations. `TF_INTRA_OP_PARALLELISM_THREADS` and `TF_INTER_OP_PARALLELISM_THREADS` controls `intra_op_parallelism_threads` and `inter_op_parallelism_threads`, which are Tensorflow configurations for multithreading. An explanation is found [here](https://stackoverflow.com/questions/41233635/meaning-of-inter-op-parallelism-threads-and-intra-op-parallelism-threads). + +For example if you wish to use 3 cores of 2 CPUs on one node, you may set the environmental variables and run DeePMD-kit as follows: +```bash +export OMP_NUM_THREADS=6 +export TF_INTRA_OP_PARALLELISM_THREADS=3 +export TF_INTER_OP_PARALLELISM_THREADS=2 +dp train input.json +``` + +### Training analysis with Tensorboard + +If enbled in json/yaml input file DeePMD-kit will create log files which can be +used to analyze training procedure with Tensorboard. For a short tutorial +please read this [document](tensorboard.html). + +## Freeze a model + +The trained neural network is extracted from a checkpoint and dumped into a database. This process is called "freezing" a model. The idea and part of our code are from [Morgan](https://blog.metaflow.fr/tensorflow-how-to-freeze-a-model-and-serve-it-with-a-python-api-d4f3596b3adc). To freeze a model, typically one does +```bash +$ dp freeze -o graph.pb +``` +in the folder where the model is trained. The output database is called `graph.pb`. + + +## 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] + +optional arguments: + -h, --help show this help message and exit + -m MODEL, --model MODEL + Frozen model file to import + -s SYSTEM, --system SYSTEM + The system dir + -S SET_PREFIX, --set-prefix SET_PREFIX + The set prefix + -n NUMB_TEST, --numb-test NUMB_TEST + The number of data for test + -r RAND_SEED, --rand-seed RAND_SEED + The random seed + --shuffle-test Shuffle test data + -d DETAIL_FILE, --detail-file DETAIL_FILE + The file containing details of energy force and virial + accuracy +``` + +## Compress a model + +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 input.json -i graph.pb -o graph-compress.pb +``` +where input.json denotes the original training input script, `-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] [-i INPUT] [-o OUTPUT] [-e EXTRAPOLATE] [-s STRIDE] + [-f FREQUENCY] [-d FOLDER] + INPUT + +positional arguments: + INPUT The input parameter file in json or yaml format, which + should be consistent with the original model parameter + file + +optional arguments: + -h, --help show this help message and exit + -i INPUT, --input INPUT + The original frozen model, which will be compressed by + the deepmd-kit + -o OUTPUT, --output OUTPUT + The compressed model + -e EXTRAPOLATE, --extrapolate EXTRAPOLATE + The scale of model extrapolation + -s STRIDE, --stride STRIDE + The uniform stride of tabulation's first table, the + second table will use 10 * stride as it's uniform + stride + -f FREQUENCY, --frequency FREQUENCY + The frequency of tabulation overflow check(If the + input environment matrix overflow the first or second + table range). By default do not check the overflow + -d FOLDER, --folder FOLDER + path to checkpoint folder +``` +**Parameter explanation** + +Model compression, which including tabulating the embedding-net. +The table is composed of fifth-order polynomial coefficients and is assembled from two sub-tables. The first sub-table takes the stride(parameter) as it's uniform stride, while the second sub-table takes 10 * 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 overflow the first or second table range) during the MD inference. + +**Justification of model compression** + +Model compression, with little loss of accuracy, can greatly speed up MD inference time. According to different simulation systems and training parameters, the speedup can reach more than 10 times at both CPU and GPU devices. At the same time, model compression can greatly change the memory usage, reducing as much as 20 times under the same hardware conditions. + +**Acceptable original model version** + +The model compression method requires that the version of DeePMD-kit used in original model generation should be 1.3 or above. If one has a frozen 1.2 model, one can first use the convenient conversion interface of DeePMD-kit-v1.2.4 to get a 1.3 executable model.(eg: ```dp convert-to-1.3 -i frozen_1.2.pb -o frozen_1.3.pb```) + +## Model inference +One may use the python interface of DeePMD-kit for model inference, an example is given as follows +```python +from deepmd import DeepPot +import numpy as np +dp = DeepPot('graph.pb') +coord = np.array([[1,0,0], [0,0,1.5], [1,0,3]]).reshape([1, -1]) +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. + + +## Run MD + +### Run MD with LAMMPS +Include deepmd in the pair_style + +#### Syntax +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 the model deviation will be computed +- keyword = *out_file* or *out_freq* or *fparam* or *atomic* or *relative* +
+    out_file value = filename
+        filename = The file name for the model deviation output. Default is model_devi.out
+    out_freq value = freq
+        freq = Frequency for the model deviation output. Default is 100.
+    fparam value = parameters
+        parameters = one or more frame parameters required for model evaluation.
+    atomic = no value is required. 
+        If this keyword is set, the model deviation of each atom will be output.
+    relative value = level
+        level = The level parameter for computing the relative model deviation
+
+ +#### Examples +``` +pair_style deepmd graph.pb +pair_style deepmd graph.pb fparam 1.2 +pair_style deepmd graph_0.pb graph_1.pb graph_2.pb out_file md.out out_freq 10 atomic relative 1.0 +``` + +#### 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). + +The model deviation evalulate the consistency of the force predictions from multiple models. By default, only the maximal, minimal and averge model deviations are output. If the key `atomic` is set, then the model deviation of force prediction of each atom will be output. + +By default, the model deviation is output in absolute value. If the keyword `relative` is set, then the relative model deviation will be output. The relative model deviation of the force on atom `i` is defined by +```math + |Df_i| +Ef_i = ------------- + |f_i| + level +``` +where `Df_i` is the absolute model deviation of the force on atom `i`, `|f_i|` is the norm of the the force and `level` is provided as the parameter of the keyword `relative`. + + +#### 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 `atom_style` of the system should be `atomic`. + +- When using the `atomic` key word of `deepmd` is set, one should not use this pair style with MPI parallelization. + + +### 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 +```bash +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. + +### 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, force and virial). The server and client communicates via the Unix domain socket or the Internet socket. The client can be started by +```bash +$ dp_ipi water.json +``` +It is noted that multiple instances of the client is allow for computing, in parallel, the interactions of multiple replica of the path-integral MD. + +`water.json` is the parameter file for the client `dp_ipi`, and [an example](./examples/ipi/water.json) 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 + } +} +``` +The option **`use_unix`** is set to `true` to activate the Unix domain socket, otherwise, the Internet socket is used. + +The option **`graph_file`** provides the file name of the frozen model. + +The `dp_ipi` gets the atom names from an [XYZ file](https://en.wikipedia.org/wiki/XYZ_file_format) provided by **`coord_file`** (meanwhile ignores all coordinates in it), and translates the names to atom types by rules provided by **`atom_type`**. + +### 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 + +water = Atoms('H2O', + positions=[(0.7601, 1.9270, 1), + (1.9575, 1, 1), + (1., 1., 1.)], + cell=[100, 100, 100], + calculator=DP(model="frozen_model.pb")) +print(water.get_potential_energy()) +print(water.get_forces()) +``` + +Optimization is also available: +```python +from ase.optimize import BFGS +dyn = BFGS(water) +dyn.run(fmax=1e-6) +print(water.get_positions()) +``` diff --git a/doc/install.rst b/doc/install.rst new file mode 100644 index 0000000000..dc2a4a627f --- /dev/null +++ b/doc/install.rst @@ -0,0 +1,10 @@ +Installation +============== + +.. toctree:: + :maxdepth: 2 + + install_easy + install_source + install_hardware-platforms + diff --git a/doc/install_easy.md b/doc/install_easy.md new file mode 100644 index 0000000000..59ac040685 --- /dev/null +++ b/doc/install_easy.md @@ -0,0 +1,39 @@ +# Easy installation methods + +There various easy methods to install DeePMD-kit. Choose one that you prefer. If you want to build by yourself, jump to the next two sections. + +After your easy installation, DeePMD-kit (`dp`) and LAMMPS (`lmp`) will be available to execute. You can try `dp -h` and `lmp -h` to see the help. `mpirun` is also available considering you may want to run LAMMPS in parallel. + +- [Install off-line packages](#Install-off-line-packages) +- [Install with conda](#Install-with-conda) +- [Install with docker](#Install-with-docker) + + +## Install off-line packages +Both CPU and GPU version offline packages are avaiable in [the Releases page](https://github.com/deepmodeling/deepmd-kit/releases). + +## Install with conda +DeePMD-kit is avaiable with [conda](https://github.com/conda/conda). Install [Anaconda](https://www.anaconda.com/distribution/#download-section) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html) first. + +To install the CPU version: +```bash +conda install deepmd-kit=*=*cpu lammps-dp=*=*cpu -c deepmodeling +``` + +To install the GPU version containing [CUDA 10.1](https://docs.nvidia.com/deploy/cuda-compatibility/index.html#binary-compatibility__table-toolkit-driver): +```bash +conda install deepmd-kit=*=*gpu lammps-dp=*=*gpu -c deepmodeling +``` + +## Install with docker +A docker for installing the DeePMD-kit is available [here](https://github.com/orgs/deepmodeling/packages/container/package/deepmd-kit). + +To pull the CPU version: +```bash +docker pull ghcr.io/deepmodeling/deepmd-kit:1.3.1_cpu +``` + +To pull the GPU version: +```bash +docker pull ghcr.io/deepmodeling/deepmd-kit:1.3.1_cuda10.1_gpu +``` diff --git a/doc/install_hardware-platforms.md b/doc/install_hardware-platforms.md new file mode 100644 index 0000000000..f326544b33 --- /dev/null +++ b/doc/install_hardware-platforms.md @@ -0,0 +1,3 @@ + +# Installation on different hardware platforms + diff --git a/doc/install_off-line-packages.md b/doc/install_off-line-packages.md new file mode 100644 index 0000000000..3d131ec733 --- /dev/null +++ b/doc/install_off-line-packages.md @@ -0,0 +1,4 @@ +#Install with Offline packages + +Both CPU and GPU version offline packages are avaiable in [the Releases page](https://github.com/deepmodeling/deepmd-kit/releases). +After your easy installation, DeePMD-kit (`dp`) and LAMMPS (`lmp`) will be available to execute. You can try `dp -h` and `lmp -h` to see the help. `mpirun` is also available considering you may want to run LAMMPS in parallel. diff --git a/doc/install_source.md b/doc/install_source.md new file mode 100644 index 0000000000..6c4da81ceb --- /dev/null +++ b/doc/install_source.md @@ -0,0 +1,173 @@ +# Install from source code + +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 --recursive https://github.com/deepmodeling/deepmd-kit.git deepmd-kit +``` +The `--recursive` option clones all [submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) needed by DeePMD-kit. + +For convenience, you may want to record the location of source to a variable, saying `deepmd_source_dir` by +```bash +cd deepmd-kit +deepmd_source_dir=`pwd` +``` +- [Install the python interaction](#install-the-python-interface) + - [Install the Tensorflow's python interface](#install-the-tensorflows-python-interface) + - [Install the DeePMD-kit's python interface](#install-the-deepmd-kits-python-interface) +- [Install the C++ interface](#install-the-c-interface) + - [Install the Tensorflow's C++ interface](#install-the-tensorflows-c-interface) + - [Install the DeePMD-kit's C++ interface](#install-the-deepmd-kits-c-interface) +- [Install LAMMPS's DeePMD-kit module](#install-lammpss-deepmd-kit-module) + + +## Install the python interface +### Install the Tensorflow's python interface +First, check the python version on your machine +```bash +python --version +``` + +We follow the virtual environment approach to install the tensorflow's Python interface. The full instruction can be found on [the tensorflow's official website](https://www.tensorflow.org/install/pip). Now we assume that the Python interface will be installed to virtual environment directory `$tensorflow_venv` +```bash +virtualenv -p python3 $tensorflow_venv +source $tensorflow_venv/bin/activate +pip install --upgrade pip +pip install --upgrade tensorflow==2.3.0 +``` +It is notice that everytime a new shell is started and one wants to use `DeePMD-kit`, the virtual environment should be activated by +```bash +source $tensorflow_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 like python3.x, it can be specified by, for example +```bash +virtualenv -p python3.7 $tensorflow_venv +``` +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==2.3.0 +``` +To verify the installation, run +```bash +python -c "import tensorflow as tf;print(tf.reduce_sum(tf.random.normal([1000, 1000])))" +``` +One should remember to activate the virtual environment every time he/she uses deepmd-kit. + +### Install the DeePMD-kit's python interface + +Execute +```bash +cd $deepmd_source_dir +pip install . +``` +To test the installation, one should firstly 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} ... + +DeePMD-kit: A deep learning package for many-body potential energy +representation and molecular dynamics + +optional arguments: + -h, --help show this help message and exit + +Valid subcommands: + {train,freeze,test} + train train a model + freeze freeze the model + test test the model +``` + +## Install the C++ interface + +If one does not need to use DeePMD-kit with Lammps or I-Pi, then the python interface installed in the previous section does everything and he/she can safely skip this section. + +### Install the Tensorflow's C++ interface + +Check the compiler version on your machine + +``` +gcc --version +``` + +The C++ interface of DeePMD-kit was tested with compiler gcc >= 4.8. It is noticed that the I-Pi support is only compiled with gcc >= 4.9. + +First the C++ interface of Tensorflow should be installed. It is noted that the version of Tensorflow should be in consistent with the python interface. You may follow [the instruction](install-tf.2.3.md) to install the corresponding C++ interface. + +### Install the DeePMD-kit's C++ interface + +Now goto the source code directory of DeePMD-kit and make a build place. +```bash +cd $deepmd_source_dir/source +mkdir build +cd build +``` +I assume you want to install DeePMD-kit into path `$deepmd_root`, then execute cmake +```bash +cmake -DTENSORFLOW_ROOT=$tensorflow_root -DCMAKE_INSTALL_PREFIX=$deepmd_root .. +``` +where the variable `tensorflow_root` stores the location where the tensorflow's C++ interface is installed. The DeePMD-kit will automatically detect if a CUDA tool-kit is available on your machine and build the GPU support accordingly. If you want to force the cmake to find CUDA tool-kit, you can speicify the key `USE_CUDA_TOOLKIT`, +```bash +cmake -DUSE_CUDA_TOOLKIT=true -DTENSORFLOW_ROOT=$tensorflow_root -DCMAKE_INSTALL_PREFIX=$deepmd_root .. +``` +and you may further asked to provide `CUDA_TOOLKIT_ROOT_DIR`. If the cmake has executed successfully, then +```bash +make +make install +``` +If everything works fine, you will have the following executable and libraries installed in `$deepmd_root/bin` and `$deepmd_root/lib` +```bash +$ ls $deepmd_root/bin +dp_ipi +$ ls $deepmd_root/lib +libdeepmd_ipi.so libdeepmd_op.so libdeepmd.so +``` + +## Install LAMMPS's DeePMD-kit module +DeePMD-kit provide module for running MD simulation with LAMMPS. Now make the DeePMD-kit module for LAMMPS. +```bash +cd $deepmd_source_dir/source/build +make lammps +``` +DeePMD-kit will generate a module called `USER-DEEPMD` in the `build` directory. Now download the LAMMPS code (`29Oct2020` or later), and uncompress it: +```bash +cd /some/workspace +wget https://github.com/lammps/lammps/archive/stable_29Oct2020.tar.gz +tar xf stable_29Oct2020.tar.gz +``` +The source code of LAMMPS is stored in directory `lammps-stable_29Oct2020`. Now go into the LAMMPS code and copy the DeePMD-kit module like this +```bash +cd lammps-stable_29Oct2020/src/ +cp -r $deepmd_source_dir/source/build/USER-DEEPMD . +``` +Now build LAMMPS +```bash +make yes-kspace +make yes-user-deepmd +make mpi -j4 +``` +The 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 end up with an executable `lmp_mpi`. +```bash +./lmp_mpi -h +``` + +The DeePMD-kit module can be removed from LAMMPS source code by +```bash +make no-user-deepmd +``` + diff --git a/doc/install_with-conda.md b/doc/install_with-conda.md new file mode 100644 index 0000000000..1927afc127 --- /dev/null +++ b/doc/install_with-conda.md @@ -0,0 +1,12 @@ +# With conda +DeePMD-kit is avaiable with [conda](https://github.com/conda/conda). Install [Anaconda](https://www.anaconda.com/distribution/#download-section) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html) first. + +To install the CPU version: +```bash +conda install deepmd-kit=*=*cpu lammps-dp=*=*cpu -c deepmodeling +``` + +To install the GPU version containing [CUDA 10.1](https://docs.nvidia.com/deploy/cuda-compatibility/index.html#binary-compatibility__table-toolkit-driver): +```bash +conda install deepmd-kit=*=*gpu lammps-dp=*=*gpu -c deepmodeling +``` diff --git a/doc/known_issues.md b/doc/known_issues.md new file mode 100644 index 0000000000..c050fb20b1 --- /dev/null +++ b/doc/known_issues.md @@ -0,0 +1 @@ +# Nuts and Bolts From a65a50fce2e09e6ab27ff3c20fe5f89ef45ffd68 Mon Sep 17 00:00:00 2001 From: tuoping Date: Mon, 19 Apr 2021 19:42:13 +0800 Subject: [PATCH 16/66] Edited license.rst and credits.rst --- LICENSE | 165 ----------------------------------------- doc/credits.md | 6 -- doc/getting-started.md | 2 +- doc/index.rst | 2 +- doc/license.md | 7 -- 5 files changed, 2 insertions(+), 180 deletions(-) delete mode 100644 LICENSE delete mode 100644 doc/credits.md delete mode 100644 doc/license.md diff --git a/LICENSE b/LICENSE deleted file mode 100644 index 0a041280bd..0000000000 --- a/LICENSE +++ /dev/null @@ -1,165 +0,0 @@ - GNU LESSER GENERAL PUBLIC LICENSE - Version 3, 29 June 2007 - - Copyright (C) 2007 Free Software Foundation, Inc. - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - - This version of the GNU Lesser General Public License incorporates -the terms and conditions of version 3 of the GNU General Public -License, supplemented by the additional permissions listed below. - - 0. Additional Definitions. - - As used herein, "this License" refers to version 3 of the GNU Lesser -General Public License, and the "GNU GPL" refers to version 3 of the GNU -General Public License. - - "The Library" refers to a covered work governed by this License, -other than an Application or a Combined Work as defined below. - - An "Application" is any work that makes use of an interface provided -by the Library, but which is not otherwise based on the Library. -Defining a subclass of a class defined by the Library is deemed a mode -of using an interface provided by the Library. - - A "Combined Work" is a work produced by combining or linking an -Application with the Library. The particular version of the Library -with which the Combined Work was made is also called the "Linked -Version". - - The "Minimal Corresponding Source" for a Combined Work means the -Corresponding Source for the Combined Work, excluding any source code -for portions of the Combined Work that, considered in isolation, are -based on the Application, and not on the Linked Version. - - The "Corresponding Application Code" for a Combined Work means the -object code and/or source code for the Application, including any data -and utility programs needed for reproducing the Combined Work from the -Application, but excluding the System Libraries of the Combined Work. - - 1. Exception to Section 3 of the GNU GPL. - - You may convey a covered work under sections 3 and 4 of this License -without being bound by section 3 of the GNU GPL. - - 2. Conveying Modified Versions. - - If you modify a copy of the Library, and, in your modifications, a -facility refers to a function or data to be supplied by an Application -that uses the facility (other than as an argument passed when the -facility is invoked), then you may convey a copy of the modified -version: - - a) under this License, provided that you make a good faith effort to - ensure that, in the event an Application does not supply the - function or data, the facility still operates, and performs - whatever part of its purpose remains meaningful, or - - b) under the GNU GPL, with none of the additional permissions of - this License applicable to that copy. - - 3. Object Code Incorporating Material from Library Header Files. - - The object code form of an Application may incorporate material from -a header file that is part of the Library. You may convey such object -code under terms of your choice, provided that, if the incorporated -material is not limited to numerical parameters, data structure -layouts and accessors, or small macros, inline functions and templates -(ten or fewer lines in length), you do both of the following: - - a) Give prominent notice with each copy of the object code that the - Library is used in it and that the Library and its use are - covered by this License. - - b) Accompany the object code with a copy of the GNU GPL and this license - document. - - 4. Combined Works. - - You may convey a Combined Work under terms of your choice that, -taken together, effectively do not restrict modification of the -portions of the Library contained in the Combined Work and reverse -engineering for debugging such modifications, if you also do each of -the following: - - a) Give prominent notice with each copy of the Combined Work that - the Library is used in it and that the Library and its use are - covered by this License. - - b) Accompany the Combined Work with a copy of the GNU GPL and this license - document. - - c) For a Combined Work that displays copyright notices during - execution, include the copyright notice for the Library among - these notices, as well as a reference directing the user to the - copies of the GNU GPL and this license document. - - d) Do one of the following: - - 0) Convey the Minimal Corresponding Source under the terms of this - License, and the Corresponding Application Code in a form - suitable for, and under terms that permit, the user to - recombine or relink the Application with a modified version of - the Linked Version to produce a modified Combined Work, in the - manner specified by section 6 of the GNU GPL for conveying - Corresponding Source. - - 1) Use a suitable shared library mechanism for linking with the - Library. A suitable mechanism is one that (a) uses at run time - a copy of the Library already present on the user's computer - system, and (b) will operate properly with a modified version - of the Library that is interface-compatible with the Linked - Version. - - e) Provide Installation Information, but only if you would otherwise - be required to provide such information under section 6 of the - GNU GPL, and only to the extent that such information is - necessary to install and execute a modified version of the - Combined Work produced by recombining or relinking the - Application with a modified version of the Linked Version. (If - you use option 4d0, the Installation Information must accompany - the Minimal Corresponding Source and Corresponding Application - Code. If you use option 4d1, you must provide the Installation - Information in the manner specified by section 6 of the GNU GPL - for conveying Corresponding Source.) - - 5. Combined Libraries. - - You may place library facilities that are a work based on the -Library side by side in a single library together with other library -facilities that are not Applications and are not covered by this -License, and convey such a combined library under terms of your -choice, if you do both of the following: - - a) Accompany the combined library with a copy of the same work based - on the Library, uncombined with any other library facilities, - conveyed under the terms of this License. - - b) Give prominent notice with the combined library that part of it - is a work based on the Library, and explaining where to find the - accompanying uncombined form of the same work. - - 6. Revised Versions of the GNU Lesser General Public License. - - The Free Software Foundation may publish revised and/or new versions -of the GNU Lesser General Public License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. - - Each version is given a distinguishing version number. If the -Library as you received it specifies that a certain numbered version -of the GNU Lesser General Public License "or any later version" -applies to it, you have the option of following the terms and -conditions either of that published version or of any later version -published by the Free Software Foundation. If the Library as you -received it does not specify a version number of the GNU Lesser -General Public License, you may choose any version of the GNU Lesser -General Public License ever published by the Free Software Foundation. - - If the Library as you received it specifies that a proxy can decide -whether future versions of the GNU Lesser General Public License shall -apply, that proxy's public statement of acceptance of any version is -permanent authorization for you to choose that version for the -Library. diff --git a/doc/credits.md b/doc/credits.md deleted file mode 100644 index 3961768b19..0000000000 --- a/doc/credits.md +++ /dev/null @@ -1,6 +0,0 @@ - -# credits - -## DeePMD Project Coordinators - -## Core Package Contributors diff --git a/doc/getting-started.md b/doc/getting-started.md index 80442897c9..a80ab11907 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -390,7 +390,7 @@ where `Df_i` is the absolute model deviation of the force on atom `i`, `|f_i|` i - When using the `atomic` key word of `deepmd` is set, one should not use this pair style with MPI parallelization. -### Long-range interaction +#### 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 ```bash pair_style deepmd graph.pb diff --git a/doc/index.rst b/doc/index.rst index 9cd2aea5ea..8c2dfae664 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -9,7 +9,7 @@ DeePMD-kit's documentation 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. -.. Important:: The project DeePMD-kit is licensed under GNU LGPLv3.0. If you use this code in any future publications, please cite this using 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. +.. Important:: The project DeePMD-kit is licensed under GNU LGPLv3.0. If you use this code in any future publications, please cite this using *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.* .. toctree:: :maxdepth: 2 diff --git a/doc/license.md b/doc/license.md deleted file mode 100644 index 31cbd0e940..0000000000 --- a/doc/license.md +++ /dev/null @@ -1,7 +0,0 @@ - -License -================== - -The project DeePMD-kit is licensed under GNU LGPLv3.0. - -If you use this code in any future publications, please cite this using 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. From bc68f899277458f3e2112ba59a4c24ea15ce3ee0 Mon Sep 17 00:00:00 2001 From: tuoping Date: Mon, 19 Apr 2021 19:43:59 +0800 Subject: [PATCH 17/66] same as before --- LICENSE.rst | 165 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/credits.rst | 40 ++++++++++++ doc/license.rst | 7 ++ 3 files changed, 212 insertions(+) create mode 100644 LICENSE.rst create mode 100644 doc/credits.rst create mode 100644 doc/license.rst diff --git a/LICENSE.rst b/LICENSE.rst new file mode 100644 index 0000000000..0a041280bd --- /dev/null +++ b/LICENSE.rst @@ -0,0 +1,165 @@ + GNU LESSER GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + + This version of the GNU Lesser General Public License incorporates +the terms and conditions of version 3 of the GNU General Public +License, supplemented by the additional permissions listed below. + + 0. Additional Definitions. + + As used herein, "this License" refers to version 3 of the GNU Lesser +General Public License, and the "GNU GPL" refers to version 3 of the GNU +General Public License. + + "The Library" refers to a covered work governed by this License, +other than an Application or a Combined Work as defined below. + + An "Application" is any work that makes use of an interface provided +by the Library, but which is not otherwise based on the Library. +Defining a subclass of a class defined by the Library is deemed a mode +of using an interface provided by the Library. + + A "Combined Work" is a work produced by combining or linking an +Application with the Library. The particular version of the Library +with which the Combined Work was made is also called the "Linked +Version". + + The "Minimal Corresponding Source" for a Combined Work means the +Corresponding Source for the Combined Work, excluding any source code +for portions of the Combined Work that, considered in isolation, are +based on the Application, and not on the Linked Version. + + The "Corresponding Application Code" for a Combined Work means the +object code and/or source code for the Application, including any data +and utility programs needed for reproducing the Combined Work from the +Application, but excluding the System Libraries of the Combined Work. + + 1. Exception to Section 3 of the GNU GPL. + + You may convey a covered work under sections 3 and 4 of this License +without being bound by section 3 of the GNU GPL. + + 2. Conveying Modified Versions. + + If you modify a copy of the Library, and, in your modifications, a +facility refers to a function or data to be supplied by an Application +that uses the facility (other than as an argument passed when the +facility is invoked), then you may convey a copy of the modified +version: + + a) under this License, provided that you make a good faith effort to + ensure that, in the event an Application does not supply the + function or data, the facility still operates, and performs + whatever part of its purpose remains meaningful, or + + b) under the GNU GPL, with none of the additional permissions of + this License applicable to that copy. + + 3. Object Code Incorporating Material from Library Header Files. + + The object code form of an Application may incorporate material from +a header file that is part of the Library. You may convey such object +code under terms of your choice, provided that, if the incorporated +material is not limited to numerical parameters, data structure +layouts and accessors, or small macros, inline functions and templates +(ten or fewer lines in length), you do both of the following: + + a) Give prominent notice with each copy of the object code that the + Library is used in it and that the Library and its use are + covered by this License. + + b) Accompany the object code with a copy of the GNU GPL and this license + document. + + 4. Combined Works. + + You may convey a Combined Work under terms of your choice that, +taken together, effectively do not restrict modification of the +portions of the Library contained in the Combined Work and reverse +engineering for debugging such modifications, if you also do each of +the following: + + a) Give prominent notice with each copy of the Combined Work that + the Library is used in it and that the Library and its use are + covered by this License. + + b) Accompany the Combined Work with a copy of the GNU GPL and this license + document. + + c) For a Combined Work that displays copyright notices during + execution, include the copyright notice for the Library among + these notices, as well as a reference directing the user to the + copies of the GNU GPL and this license document. + + d) Do one of the following: + + 0) Convey the Minimal Corresponding Source under the terms of this + License, and the Corresponding Application Code in a form + suitable for, and under terms that permit, the user to + recombine or relink the Application with a modified version of + the Linked Version to produce a modified Combined Work, in the + manner specified by section 6 of the GNU GPL for conveying + Corresponding Source. + + 1) Use a suitable shared library mechanism for linking with the + Library. A suitable mechanism is one that (a) uses at run time + a copy of the Library already present on the user's computer + system, and (b) will operate properly with a modified version + of the Library that is interface-compatible with the Linked + Version. + + e) Provide Installation Information, but only if you would otherwise + be required to provide such information under section 6 of the + GNU GPL, and only to the extent that such information is + necessary to install and execute a modified version of the + Combined Work produced by recombining or relinking the + Application with a modified version of the Linked Version. (If + you use option 4d0, the Installation Information must accompany + the Minimal Corresponding Source and Corresponding Application + Code. If you use option 4d1, you must provide the Installation + Information in the manner specified by section 6 of the GNU GPL + for conveying Corresponding Source.) + + 5. Combined Libraries. + + You may place library facilities that are a work based on the +Library side by side in a single library together with other library +facilities that are not Applications and are not covered by this +License, and convey such a combined library under terms of your +choice, if you do both of the following: + + a) Accompany the combined library with a copy of the same work based + on the Library, uncombined with any other library facilities, + conveyed under the terms of this License. + + b) Give prominent notice with the combined library that part of it + is a work based on the Library, and explaining where to find the + accompanying uncombined form of the same work. + + 6. Revised Versions of the GNU Lesser General Public License. + + The Free Software Foundation may publish revised and/or new versions +of the GNU Lesser General Public License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the +Library as you received it specifies that a certain numbered version +of the GNU Lesser General Public License "or any later version" +applies to it, you have the option of following the terms and +conditions either of that published version or of any later version +published by the Free Software Foundation. If the Library as you +received it does not specify a version number of the GNU Lesser +General Public License, you may choose any version of the GNU Lesser +General Public License ever published by the Free Software Foundation. + + If the Library as you received it specifies that a proxy can decide +whether future versions of the GNU Lesser General Public License shall +apply, that proxy's public statement of acceptance of any version is +permanent authorization for you to choose that version for the +Library. diff --git a/doc/credits.rst b/doc/credits.rst new file mode 100644 index 0000000000..438b308075 --- /dev/null +++ b/doc/credits.rst @@ -0,0 +1,40 @@ +******************* +Authors and Credits +******************* + +Core Package Contributors +========================= + +* amcadmus +* AnguseZhang +* ass7798 +* DiracMD +* dongdawn +* felix5572 +* jameswind +* jiaweile +* jxxiaoshaoye +* kevinwenminion +* KuangYu +* lqs0609 +* mohanchen +* njzjz +* robinzyb +* tansongchen +* tuoping +* Unboundwill +* Vibsteamer +* y1xiaoc +* YWolfeee +* ZiyaoLi + +Other Credits +============= + +* Zhang ZiXuan for designing the Deepmodeling logo. +* Everyone on the `Deepmodeling mailing list` for contributing to many discussions and decisions! + +(If you have contributed to the ``deepmd-kit`` core package and your name is missing, +please send an email to the contributors, or +`open a pull request for this page `_ +in the `deepmd-kit repository `_) diff --git a/doc/license.rst b/doc/license.rst new file mode 100644 index 0000000000..9e36eb6946 --- /dev/null +++ b/doc/license.rst @@ -0,0 +1,7 @@ + +License +================== + +The project DeePMD-kit is licensed under GNU LGPLv3.0. + +.. include:: ../LICENSE.rst From fcc85a76ee835906a3d90f94d921ae533a819ba2 Mon Sep 17 00:00:00 2001 From: tuoping Date: Tue, 20 Apr 2021 14:13:16 +0800 Subject: [PATCH 18/66] Modified pair-style-deepmd syntax part --- doc/getting-started.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/getting-started.md b/doc/getting-started.md index a80ab11907..f169cb8afa 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -341,6 +341,7 @@ where `e`, `f` and `v` are predicted energy, force and virial of the system, res Include deepmd in the pair_style #### Syntax +``` pair_style deepmd models ... keyword value ... ``` - deepmd = style of this pair_style From 38f713b21a481a435a7aed68dc7880735474fa9f Mon Sep 17 00:00:00 2001 From: tuoping Date: Tue, 20 Apr 2021 19:33:13 +0800 Subject: [PATCH 19/66] Fixed the collapsed table in getting-started#prepare-data by adding extension sphinx-markdown-tables in conf.py --- doc/conf.py | 1 + doc/getting-started.md | 20 ++++++----- doc/install_off-line-packages.md | 4 --- doc/lammps-pair-style-deepmd.md | 57 -------------------------------- 4 files changed, 12 insertions(+), 70 deletions(-) delete mode 100644 doc/install_off-line-packages.md delete mode 100644 doc/lammps-pair-style-deepmd.md diff --git a/doc/conf.py b/doc/conf.py index e6c4c7d032..4ca8fad0dd 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -30,6 +30,7 @@ extensions = [ 'recommonmark', "sphinx_rtd_theme", + 'sphinx_markdown_tables', 'sphinx.ext.autosummary' ] diff --git a/doc/getting-started.md b/doc/getting-started.md index f169cb8afa..8c7214751e 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -18,14 +18,16 @@ In this text, we will call the deep neural network that is used to represent the ## Prepare data One needs to provide the following information to train a model: the atom type, the simulation box, the atom coordinate, the atom force, system energy and virial. A snapshot of a system that contains these information is called a **frame**. We 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 + The frames of the system are stored in two formats. A raw file is a plain text file with each information item written in one file and one frame written on one line. The default files that provide box, coordinate, force, energy and virial are `box.raw`, `coord.raw`, `force.raw`, `energy.raw` and `virial.raw`, respectively. *We recommend you use these file names*. Here is an example of force.raw: ```bash @@ -408,7 +410,7 @@ $ dp_ipi water.json ``` It is noted that multiple instances of the client is allow for computing, in parallel, the interactions of multiple replica of the path-integral MD. -`water.json` is the parameter file for the client `dp_ipi`, and [an example](./examples/ipi/water.json) is provided: +`water.json` is the parameter file for the client `dp_ipi`, and [an example](https://github.com/tuoping/deepmd-kit/blob/devel/examples/water/ipi/water.json) is provided: ```json { "verbose": false, diff --git a/doc/install_off-line-packages.md b/doc/install_off-line-packages.md deleted file mode 100644 index 3d131ec733..0000000000 --- a/doc/install_off-line-packages.md +++ /dev/null @@ -1,4 +0,0 @@ -#Install with Offline packages - -Both CPU and GPU version offline packages are avaiable in [the Releases page](https://github.com/deepmodeling/deepmd-kit/releases). -After your easy installation, DeePMD-kit (`dp`) and LAMMPS (`lmp`) will be available to execute. You can try `dp -h` and `lmp -h` to see the help. `mpirun` is also available considering you may want to run LAMMPS in parallel. diff --git a/doc/lammps-pair-style-deepmd.md b/doc/lammps-pair-style-deepmd.md deleted file mode 100644 index 0a39e7362c..0000000000 --- a/doc/lammps-pair-style-deepmd.md +++ /dev/null @@ -1,57 +0,0 @@ -# pair_style deepmd command - -## Syntax -``` -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 the model deviation will be computed -- keyword = *out_file* or *out_freq* or *fparam* or *atomic* or *relative* -
-    out_file value = filename
-        filename = The file name for the model deviation output. Default is model_devi.out
-    out_freq value = freq
-        freq = Frequency for the model deviation output. Default is 100.
-    fparam value = parameters
-        parameters = one or more frame parameters required for model evaluation.
-    atomic = no value is required. 
-        If this keyword is set, the model deviation of each atom will be output.
-    relative value = level
-        level = The level parameter for computing the relative model deviation
-
- -## Examples -``` -pair_style deepmd graph.pb -pair_style deepmd graph.pb fparam 1.2 -pair_style deepmd graph_0.pb graph_1.pb graph_2.pb out_file md.out out_freq 10 atomic relative 1.0 -``` - -## 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). - -The model deviation evalulate the consistency of the force predictions from multiple models. By default, only the maximal, minimal and averge model deviations are output. If the key `atomic` is set, then the model deviation of force prediction of each atom will be output. - -By default, the model deviation is output in absolute value. If the keyword `relative` is set, then the relative model deviation will be output. The relative model deviation of the force on atom `i` is defined by -```math - |Df_i| -Ef_i = ------------- - |f_i| + level -``` -where `Df_i` is the absolute model deviation of the force on atom `i`, `|f_i|` is the norm of the the force and `level` is provided as the parameter of the keyword `relative`. - - -## 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 `atom_style` of the system should be `atomic`. - -- When using the `atomic` key word of `deepmd` is set, one should not use this pair style with MPI parallelization. - - -[DP]:https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.143001 -[DP-SE]:https://arxiv.org/abs/1805.09003 From 19ff8a35385dc894fdf34d5dca574c34d71633b3 Mon Sep 17 00:00:00 2001 From: tuoping Date: Tue, 20 Apr 2021 19:48:31 +0800 Subject: [PATCH 20/66] Added sphinx-markdown-table in requirements.txt --- requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements.txt b/requirements.txt index f57f40b611..42fb7caecb 100644 --- a/requirements.txt +++ b/requirements.txt @@ -4,3 +4,4 @@ pyyaml dargs >= 0.2.1 tqdm typing_extensions +sphinx_markdown_tables From 52a182e977c2479bde6b02d3b20cfe0fbd66f2b8 Mon Sep 17 00:00:00 2001 From: tuoping Date: Wed, 21 Apr 2021 10:33:02 +0800 Subject: [PATCH 21/66] Modification after Merge --- doc/data-conversion.md | 5 ----- doc/getting-started.md | 17 ----------------- doc/index.rst | 2 +- 3 files changed, 1 insertion(+), 23 deletions(-) delete mode 100644 doc/data-conversion.md diff --git a/doc/data-conversion.md b/doc/data-conversion.md deleted file mode 100644 index a0c739ad97..0000000000 --- a/doc/data-conversion.md +++ /dev/null @@ -1,5 +0,0 @@ -# Data conversion - -Data conversion, from different fp packages - - diff --git a/doc/getting-started.md b/doc/getting-started.md index bd58594b72..5a3e8d2a5d 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -1,21 +1,4 @@ -<<<<<<< HEAD:doc/getting-started.md -# Getting started -======= -- [Use DeePMD-kit](#use-deepmd-kit) - - [Prepare data](#prepare-data) - - [Train a model](#train-a-model) - - [Freeze a model](#freeze-a-model) - - [Test a model](#test-a-model) - - [Compress a model](#compress-a-model) - - [Model inference](#model-inference) - - [Run MD with Lammps](#run-md-with-lammps) - - [Include deepmd in the pair style](#include-deepmd-in-the-pair-style) - - [Long-range interaction](#long-range-interaction) - - [Run path-integral MD with i-PI](#run-path-integral-md-with-i-pi) - - [Use deep potential with ASE](#use-deep-potential-with-ase) - # Use DeePMD-kit ->>>>>>> origin/devel:doc/use-deepmd-kit.md In this text, we will call the deep neural network that is used to represent the interatomic interactions (Deep Potential) the **model**. The typical procedure of using DeePMD-kit is 1. [Prepare data](#prepare-data) diff --git a/doc/index.rst b/doc/index.rst index 8c2dfae664..63a4ffef5c 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -26,7 +26,7 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r :maxdepth: 2 :caption: Data and Parameters - data-conversion + data-conv train-input .. toctree:: From eae66612c5a2b10b8f99968322b5686bcf154e94 Mon Sep 17 00:00:00 2001 From: tuoping Date: Wed, 21 Apr 2021 11:19:43 +0800 Subject: [PATCH 22/66] modified superlinks in getting-started.md --- doc/credits.rst | 2 +- doc/getting-started.md | 24 ++--- doc/install.rst | 6 +- doc/install_easy.md | 39 ------- doc/install_hardware-platforms.md | 3 - doc/install_source.md | 173 ------------------------------ doc/install_with-conda.md | 12 --- doc/tensorboard.md | 2 +- doc/train-input.rst | 2 +- 9 files changed, 18 insertions(+), 245 deletions(-) delete mode 100644 doc/install_easy.md delete mode 100644 doc/install_hardware-platforms.md delete mode 100644 doc/install_source.md delete mode 100644 doc/install_with-conda.md diff --git a/doc/credits.rst b/doc/credits.rst index 438b308075..a58d0b825c 100644 --- a/doc/credits.rst +++ b/doc/credits.rst @@ -17,7 +17,7 @@ Core Package Contributors * kevinwenminion * KuangYu * lqs0609 -* mohanchen +* marian-code * njzjz * robinzyb * tansongchen diff --git a/doc/getting-started.md b/doc/getting-started.md index 5a3e8d2a5d..59e0b12794 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -1,4 +1,4 @@ -# Use DeePMD-kit +# Getting Started In this text, we will call the deep neural network that is used to represent the interatomic interactions (Deep Potential) the **model**. The typical procedure of using DeePMD-kit is 1. [Prepare data](#prepare-data) @@ -78,16 +78,16 @@ One can use the a convenient tool `dpdata` to convert data directly from the out 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. DeePMD-kit implements the following descriptors: -1. [`se_e2_a`](train-se-e2-a.md#descriptor): 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. -4. `loc_frame`: Defines a local frame at each atom, and the compute the descriptor as local coordinates under this frame. -5. [`hybrid`](train-hybrid.md): Concate a list of descriptors to form a new descriptor. +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. +4. loc_frame: Defines a local frame at each atom, and the compute the descriptor as local coordinates under this frame. +5. [hybrid](train-hybrid.md): Concate a list of descriptors to form a new descriptor. The fitting of the following physical properties are supported -1. [`ener`](train-se-e2-a.md#fitting) Fitting the energy of the system. The force (derivative with atom positions) and the virial (derivative with the box tensor) can also be trained. See [the example](train-se-e2-a.md#loss). -2. `dipole` The dipole moment. -3. `polar` The polarizability. +1. [ener](train-se-e2-a.md): Fitting the energy of the system. The force (derivative with atom positions) and the virial (derivative with the box tensor) can also be trained. See [the example](train-se-e2-a.md). +2. dipole: The dipole moment. +3. polar: The polarizability. ### Training @@ -96,7 +96,7 @@ The training can be invoked by ```bash $ dp train input.json ``` -where `input.json` is the name of the input script. See [the example](train-se-e2-a.md#train-a-deep-potential-model) for more details. +where `input.json` is the name of the input script. See [the example](train-se-e2-a.md) for more details. During the training, checkpoints will be written to files with prefix `save_ckpt` every `save_freq` training steps. @@ -134,7 +134,7 @@ dp train input.json If enbled in json/yaml input file DeePMD-kit will create log files which can be used to analyze training procedure with Tensorboard. For a short tutorial -please read this [document](tensorboard.html). +please read this [document](tensorboard.md). ## Freeze a model @@ -321,7 +321,7 @@ $ dp_ipi water.json ``` It is noted that multiple instances of the client is allow for computing, in parallel, the interactions of multiple replica of the path-integral MD. -`water.json` is the parameter file for the client `dp_ipi`, and [an example](https://github.com/tuoping/deepmd-kit/blob/devel/examples/water/ipi/water.json) is provided: +`water.json` is the parameter file for the client `dp_ipi`, and an example is provided: ```json { "verbose": false, diff --git a/doc/install.rst b/doc/install.rst index dc2a4a627f..03b18cd5ee 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -4,7 +4,7 @@ Installation .. toctree:: :maxdepth: 2 - install_easy - install_source - install_hardware-platforms + install-easy + install-source + install-hardware-platforms diff --git a/doc/install_easy.md b/doc/install_easy.md deleted file mode 100644 index 59ac040685..0000000000 --- a/doc/install_easy.md +++ /dev/null @@ -1,39 +0,0 @@ -# Easy installation methods - -There various easy methods to install DeePMD-kit. Choose one that you prefer. If you want to build by yourself, jump to the next two sections. - -After your easy installation, DeePMD-kit (`dp`) and LAMMPS (`lmp`) will be available to execute. You can try `dp -h` and `lmp -h` to see the help. `mpirun` is also available considering you may want to run LAMMPS in parallel. - -- [Install off-line packages](#Install-off-line-packages) -- [Install with conda](#Install-with-conda) -- [Install with docker](#Install-with-docker) - - -## Install off-line packages -Both CPU and GPU version offline packages are avaiable in [the Releases page](https://github.com/deepmodeling/deepmd-kit/releases). - -## Install with conda -DeePMD-kit is avaiable with [conda](https://github.com/conda/conda). Install [Anaconda](https://www.anaconda.com/distribution/#download-section) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html) first. - -To install the CPU version: -```bash -conda install deepmd-kit=*=*cpu lammps-dp=*=*cpu -c deepmodeling -``` - -To install the GPU version containing [CUDA 10.1](https://docs.nvidia.com/deploy/cuda-compatibility/index.html#binary-compatibility__table-toolkit-driver): -```bash -conda install deepmd-kit=*=*gpu lammps-dp=*=*gpu -c deepmodeling -``` - -## Install with docker -A docker for installing the DeePMD-kit is available [here](https://github.com/orgs/deepmodeling/packages/container/package/deepmd-kit). - -To pull the CPU version: -```bash -docker pull ghcr.io/deepmodeling/deepmd-kit:1.3.1_cpu -``` - -To pull the GPU version: -```bash -docker pull ghcr.io/deepmodeling/deepmd-kit:1.3.1_cuda10.1_gpu -``` diff --git a/doc/install_hardware-platforms.md b/doc/install_hardware-platforms.md deleted file mode 100644 index f326544b33..0000000000 --- a/doc/install_hardware-platforms.md +++ /dev/null @@ -1,3 +0,0 @@ - -# Installation on different hardware platforms - diff --git a/doc/install_source.md b/doc/install_source.md deleted file mode 100644 index 6c4da81ceb..0000000000 --- a/doc/install_source.md +++ /dev/null @@ -1,173 +0,0 @@ -# Install from source code - -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 --recursive https://github.com/deepmodeling/deepmd-kit.git deepmd-kit -``` -The `--recursive` option clones all [submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) needed by DeePMD-kit. - -For convenience, you may want to record the location of source to a variable, saying `deepmd_source_dir` by -```bash -cd deepmd-kit -deepmd_source_dir=`pwd` -``` -- [Install the python interaction](#install-the-python-interface) - - [Install the Tensorflow's python interface](#install-the-tensorflows-python-interface) - - [Install the DeePMD-kit's python interface](#install-the-deepmd-kits-python-interface) -- [Install the C++ interface](#install-the-c-interface) - - [Install the Tensorflow's C++ interface](#install-the-tensorflows-c-interface) - - [Install the DeePMD-kit's C++ interface](#install-the-deepmd-kits-c-interface) -- [Install LAMMPS's DeePMD-kit module](#install-lammpss-deepmd-kit-module) - - -## Install the python interface -### Install the Tensorflow's python interface -First, check the python version on your machine -```bash -python --version -``` - -We follow the virtual environment approach to install the tensorflow's Python interface. The full instruction can be found on [the tensorflow's official website](https://www.tensorflow.org/install/pip). Now we assume that the Python interface will be installed to virtual environment directory `$tensorflow_venv` -```bash -virtualenv -p python3 $tensorflow_venv -source $tensorflow_venv/bin/activate -pip install --upgrade pip -pip install --upgrade tensorflow==2.3.0 -``` -It is notice that everytime a new shell is started and one wants to use `DeePMD-kit`, the virtual environment should be activated by -```bash -source $tensorflow_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 like python3.x, it can be specified by, for example -```bash -virtualenv -p python3.7 $tensorflow_venv -``` -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==2.3.0 -``` -To verify the installation, run -```bash -python -c "import tensorflow as tf;print(tf.reduce_sum(tf.random.normal([1000, 1000])))" -``` -One should remember to activate the virtual environment every time he/she uses deepmd-kit. - -### Install the DeePMD-kit's python interface - -Execute -```bash -cd $deepmd_source_dir -pip install . -``` -To test the installation, one should firstly 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} ... - -DeePMD-kit: A deep learning package for many-body potential energy -representation and molecular dynamics - -optional arguments: - -h, --help show this help message and exit - -Valid subcommands: - {train,freeze,test} - train train a model - freeze freeze the model - test test the model -``` - -## Install the C++ interface - -If one does not need to use DeePMD-kit with Lammps or I-Pi, then the python interface installed in the previous section does everything and he/she can safely skip this section. - -### Install the Tensorflow's C++ interface - -Check the compiler version on your machine - -``` -gcc --version -``` - -The C++ interface of DeePMD-kit was tested with compiler gcc >= 4.8. It is noticed that the I-Pi support is only compiled with gcc >= 4.9. - -First the C++ interface of Tensorflow should be installed. It is noted that the version of Tensorflow should be in consistent with the python interface. You may follow [the instruction](install-tf.2.3.md) to install the corresponding C++ interface. - -### Install the DeePMD-kit's C++ interface - -Now goto the source code directory of DeePMD-kit and make a build place. -```bash -cd $deepmd_source_dir/source -mkdir build -cd build -``` -I assume you want to install DeePMD-kit into path `$deepmd_root`, then execute cmake -```bash -cmake -DTENSORFLOW_ROOT=$tensorflow_root -DCMAKE_INSTALL_PREFIX=$deepmd_root .. -``` -where the variable `tensorflow_root` stores the location where the tensorflow's C++ interface is installed. The DeePMD-kit will automatically detect if a CUDA tool-kit is available on your machine and build the GPU support accordingly. If you want to force the cmake to find CUDA tool-kit, you can speicify the key `USE_CUDA_TOOLKIT`, -```bash -cmake -DUSE_CUDA_TOOLKIT=true -DTENSORFLOW_ROOT=$tensorflow_root -DCMAKE_INSTALL_PREFIX=$deepmd_root .. -``` -and you may further asked to provide `CUDA_TOOLKIT_ROOT_DIR`. If the cmake has executed successfully, then -```bash -make -make install -``` -If everything works fine, you will have the following executable and libraries installed in `$deepmd_root/bin` and `$deepmd_root/lib` -```bash -$ ls $deepmd_root/bin -dp_ipi -$ ls $deepmd_root/lib -libdeepmd_ipi.so libdeepmd_op.so libdeepmd.so -``` - -## Install LAMMPS's DeePMD-kit module -DeePMD-kit provide module for running MD simulation with LAMMPS. Now make the DeePMD-kit module for LAMMPS. -```bash -cd $deepmd_source_dir/source/build -make lammps -``` -DeePMD-kit will generate a module called `USER-DEEPMD` in the `build` directory. Now download the LAMMPS code (`29Oct2020` or later), and uncompress it: -```bash -cd /some/workspace -wget https://github.com/lammps/lammps/archive/stable_29Oct2020.tar.gz -tar xf stable_29Oct2020.tar.gz -``` -The source code of LAMMPS is stored in directory `lammps-stable_29Oct2020`. Now go into the LAMMPS code and copy the DeePMD-kit module like this -```bash -cd lammps-stable_29Oct2020/src/ -cp -r $deepmd_source_dir/source/build/USER-DEEPMD . -``` -Now build LAMMPS -```bash -make yes-kspace -make yes-user-deepmd -make mpi -j4 -``` -The 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 end up with an executable `lmp_mpi`. -```bash -./lmp_mpi -h -``` - -The DeePMD-kit module can be removed from LAMMPS source code by -```bash -make no-user-deepmd -``` - diff --git a/doc/install_with-conda.md b/doc/install_with-conda.md deleted file mode 100644 index 1927afc127..0000000000 --- a/doc/install_with-conda.md +++ /dev/null @@ -1,12 +0,0 @@ -# With conda -DeePMD-kit is avaiable with [conda](https://github.com/conda/conda). Install [Anaconda](https://www.anaconda.com/distribution/#download-section) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html) first. - -To install the CPU version: -```bash -conda install deepmd-kit=*=*cpu lammps-dp=*=*cpu -c deepmodeling -``` - -To install the GPU version containing [CUDA 10.1](https://docs.nvidia.com/deploy/cuda-compatibility/index.html#binary-compatibility__table-toolkit-driver): -```bash -conda install deepmd-kit=*=*gpu lammps-dp=*=*gpu -c deepmodeling -``` diff --git a/doc/tensorboard.md b/doc/tensorboard.md index 826648c9b6..dafbdffb2c 100644 --- a/doc/tensorboard.md +++ b/doc/tensorboard.md @@ -1,4 +1,4 @@ -# TensorBoard usage +# TensorBoard Usage TensorBoard provides the visualization and tooling needed for machine learning experimentation. A full instruction of tensorboard can be found diff --git a/doc/train-input.rst b/doc/train-input.rst index aa6c7bd01e..0a12239597 100644 --- a/doc/train-input.rst +++ b/doc/train-input.rst @@ -1,3 +1,3 @@ -Training parameters +Training Parameters ====================================== .. include:: train-input-auto.rst From 328df53b2331bb47f3b1201de48302a1fb2d64d5 Mon Sep 17 00:00:00 2001 From: tuoping Date: Wed, 21 Apr 2021 11:20:15 +0800 Subject: [PATCH 23/66] same --- doc/install-easy.md | 39 +++++++ doc/install-hardware-platforms.md | 3 + doc/install-source.md | 173 ++++++++++++++++++++++++++++++ 3 files changed, 215 insertions(+) create mode 100644 doc/install-easy.md create mode 100644 doc/install-hardware-platforms.md create mode 100644 doc/install-source.md diff --git a/doc/install-easy.md b/doc/install-easy.md new file mode 100644 index 0000000000..59ac040685 --- /dev/null +++ b/doc/install-easy.md @@ -0,0 +1,39 @@ +# Easy installation methods + +There various easy methods to install DeePMD-kit. Choose one that you prefer. If you want to build by yourself, jump to the next two sections. + +After your easy installation, DeePMD-kit (`dp`) and LAMMPS (`lmp`) will be available to execute. You can try `dp -h` and `lmp -h` to see the help. `mpirun` is also available considering you may want to run LAMMPS in parallel. + +- [Install off-line packages](#Install-off-line-packages) +- [Install with conda](#Install-with-conda) +- [Install with docker](#Install-with-docker) + + +## Install off-line packages +Both CPU and GPU version offline packages are avaiable in [the Releases page](https://github.com/deepmodeling/deepmd-kit/releases). + +## Install with conda +DeePMD-kit is avaiable with [conda](https://github.com/conda/conda). Install [Anaconda](https://www.anaconda.com/distribution/#download-section) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html) first. + +To install the CPU version: +```bash +conda install deepmd-kit=*=*cpu lammps-dp=*=*cpu -c deepmodeling +``` + +To install the GPU version containing [CUDA 10.1](https://docs.nvidia.com/deploy/cuda-compatibility/index.html#binary-compatibility__table-toolkit-driver): +```bash +conda install deepmd-kit=*=*gpu lammps-dp=*=*gpu -c deepmodeling +``` + +## Install with docker +A docker for installing the DeePMD-kit is available [here](https://github.com/orgs/deepmodeling/packages/container/package/deepmd-kit). + +To pull the CPU version: +```bash +docker pull ghcr.io/deepmodeling/deepmd-kit:1.3.1_cpu +``` + +To pull the GPU version: +```bash +docker pull ghcr.io/deepmodeling/deepmd-kit:1.3.1_cuda10.1_gpu +``` diff --git a/doc/install-hardware-platforms.md b/doc/install-hardware-platforms.md new file mode 100644 index 0000000000..f326544b33 --- /dev/null +++ b/doc/install-hardware-platforms.md @@ -0,0 +1,3 @@ + +# Installation on different hardware platforms + diff --git a/doc/install-source.md b/doc/install-source.md new file mode 100644 index 0000000000..6c4da81ceb --- /dev/null +++ b/doc/install-source.md @@ -0,0 +1,173 @@ +# Install from source code + +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 --recursive https://github.com/deepmodeling/deepmd-kit.git deepmd-kit +``` +The `--recursive` option clones all [submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) needed by DeePMD-kit. + +For convenience, you may want to record the location of source to a variable, saying `deepmd_source_dir` by +```bash +cd deepmd-kit +deepmd_source_dir=`pwd` +``` +- [Install the python interaction](#install-the-python-interface) + - [Install the Tensorflow's python interface](#install-the-tensorflows-python-interface) + - [Install the DeePMD-kit's python interface](#install-the-deepmd-kits-python-interface) +- [Install the C++ interface](#install-the-c-interface) + - [Install the Tensorflow's C++ interface](#install-the-tensorflows-c-interface) + - [Install the DeePMD-kit's C++ interface](#install-the-deepmd-kits-c-interface) +- [Install LAMMPS's DeePMD-kit module](#install-lammpss-deepmd-kit-module) + + +## Install the python interface +### Install the Tensorflow's python interface +First, check the python version on your machine +```bash +python --version +``` + +We follow the virtual environment approach to install the tensorflow's Python interface. The full instruction can be found on [the tensorflow's official website](https://www.tensorflow.org/install/pip). Now we assume that the Python interface will be installed to virtual environment directory `$tensorflow_venv` +```bash +virtualenv -p python3 $tensorflow_venv +source $tensorflow_venv/bin/activate +pip install --upgrade pip +pip install --upgrade tensorflow==2.3.0 +``` +It is notice that everytime a new shell is started and one wants to use `DeePMD-kit`, the virtual environment should be activated by +```bash +source $tensorflow_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 like python3.x, it can be specified by, for example +```bash +virtualenv -p python3.7 $tensorflow_venv +``` +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==2.3.0 +``` +To verify the installation, run +```bash +python -c "import tensorflow as tf;print(tf.reduce_sum(tf.random.normal([1000, 1000])))" +``` +One should remember to activate the virtual environment every time he/she uses deepmd-kit. + +### Install the DeePMD-kit's python interface + +Execute +```bash +cd $deepmd_source_dir +pip install . +``` +To test the installation, one should firstly 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} ... + +DeePMD-kit: A deep learning package for many-body potential energy +representation and molecular dynamics + +optional arguments: + -h, --help show this help message and exit + +Valid subcommands: + {train,freeze,test} + train train a model + freeze freeze the model + test test the model +``` + +## Install the C++ interface + +If one does not need to use DeePMD-kit with Lammps or I-Pi, then the python interface installed in the previous section does everything and he/she can safely skip this section. + +### Install the Tensorflow's C++ interface + +Check the compiler version on your machine + +``` +gcc --version +``` + +The C++ interface of DeePMD-kit was tested with compiler gcc >= 4.8. It is noticed that the I-Pi support is only compiled with gcc >= 4.9. + +First the C++ interface of Tensorflow should be installed. It is noted that the version of Tensorflow should be in consistent with the python interface. You may follow [the instruction](install-tf.2.3.md) to install the corresponding C++ interface. + +### Install the DeePMD-kit's C++ interface + +Now goto the source code directory of DeePMD-kit and make a build place. +```bash +cd $deepmd_source_dir/source +mkdir build +cd build +``` +I assume you want to install DeePMD-kit into path `$deepmd_root`, then execute cmake +```bash +cmake -DTENSORFLOW_ROOT=$tensorflow_root -DCMAKE_INSTALL_PREFIX=$deepmd_root .. +``` +where the variable `tensorflow_root` stores the location where the tensorflow's C++ interface is installed. The DeePMD-kit will automatically detect if a CUDA tool-kit is available on your machine and build the GPU support accordingly. If you want to force the cmake to find CUDA tool-kit, you can speicify the key `USE_CUDA_TOOLKIT`, +```bash +cmake -DUSE_CUDA_TOOLKIT=true -DTENSORFLOW_ROOT=$tensorflow_root -DCMAKE_INSTALL_PREFIX=$deepmd_root .. +``` +and you may further asked to provide `CUDA_TOOLKIT_ROOT_DIR`. If the cmake has executed successfully, then +```bash +make +make install +``` +If everything works fine, you will have the following executable and libraries installed in `$deepmd_root/bin` and `$deepmd_root/lib` +```bash +$ ls $deepmd_root/bin +dp_ipi +$ ls $deepmd_root/lib +libdeepmd_ipi.so libdeepmd_op.so libdeepmd.so +``` + +## Install LAMMPS's DeePMD-kit module +DeePMD-kit provide module for running MD simulation with LAMMPS. Now make the DeePMD-kit module for LAMMPS. +```bash +cd $deepmd_source_dir/source/build +make lammps +``` +DeePMD-kit will generate a module called `USER-DEEPMD` in the `build` directory. Now download the LAMMPS code (`29Oct2020` or later), and uncompress it: +```bash +cd /some/workspace +wget https://github.com/lammps/lammps/archive/stable_29Oct2020.tar.gz +tar xf stable_29Oct2020.tar.gz +``` +The source code of LAMMPS is stored in directory `lammps-stable_29Oct2020`. Now go into the LAMMPS code and copy the DeePMD-kit module like this +```bash +cd lammps-stable_29Oct2020/src/ +cp -r $deepmd_source_dir/source/build/USER-DEEPMD . +``` +Now build LAMMPS +```bash +make yes-kspace +make yes-user-deepmd +make mpi -j4 +``` +The 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 end up with an executable `lmp_mpi`. +```bash +./lmp_mpi -h +``` + +The DeePMD-kit module can be removed from LAMMPS source code by +```bash +make no-user-deepmd +``` + From 35f46fbcbf0174c7b7c469b56ee09a19b7f52c36 Mon Sep 17 00:00:00 2001 From: tuoping Date: Wed, 21 Apr 2021 15:12:46 +0800 Subject: [PATCH 24/66] Something is imperfect with the url. I can't link to #section in another .md file. So I changed all the external links in getting-started.md, and deleted all the #... parts. --- doc/api.rst | 8 ++------ doc/conf.py | 10 +++++----- doc/getting-started.md | 10 ++++++---- 3 files changed, 13 insertions(+), 15 deletions(-) diff --git a/doc/api.rst b/doc/api.rst index ef5260cb3b..f5a541cbf6 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -9,15 +9,11 @@ API :members: :undoc-members: -.. automodule:: deepmd.infer.dataModifier +.. automodule:: deepmd.infer.data_modifier :members: :undoc-members: -.. automodule:: deepmd.utils.dataSystem - :members: - :undoc-members: - -.. automodule:: deepmd.descriptor.dipole +.. automodule:: deepmd.utils.data_system :members: :undoc-members: diff --git a/doc/conf.py b/doc/conf.py index 4ca8fad0dd..d3f25baf57 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -10,10 +10,11 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -import os -import sys -sys.path.append(os.path.abspath("..")) -print(sys.path) +# import os +# import sys +import recommonmark +from recommonmark.transform import AutoStructify + # -- Project information ----------------------------------------------------- @@ -34,7 +35,6 @@ 'sphinx.ext.autosummary' ] - # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/doc/getting-started.md b/doc/getting-started.md index 59e0b12794..1384ef7306 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -78,11 +78,11 @@ One can use the a convenient tool `dpdata` to convert data directly from the out 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. 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. +1. [se_e2_a](train-se-e2-a): 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): DeepPot-SE constructed from radial information of atomic configurations. The embedding takes the distance between atoms as input. +3. [se_e3](train-se-e3): DeepPot-SE constructed from all information (both angular and radial) of atomic configurations. The embedding takes angles between two neighboring atoms as input. 4. loc_frame: Defines a local frame at each atom, and the compute the descriptor as local coordinates under this frame. -5. [hybrid](train-hybrid.md): Concate a list of descriptors to form a new descriptor. +5. [hybrid](train-hybrid): Concate a list of descriptors to form a new descriptor. The fitting of the following physical properties are supported 1. [ener](train-se-e2-a.md): Fitting the energy of the system. The force (derivative with atom positions) and the virial (derivative with the box tensor) can also be trained. See [the example](train-se-e2-a.md). @@ -367,3 +367,5 @@ dyn = BFGS(water) dyn.run(fmax=1e-6) print(water.get_positions()) ``` +[DP]:https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.143001 +[DP-SE]:https://arxiv.org/abs/1805.09003 From aa00bc8aad7b13b48748cc3b75575f0a842b1640 Mon Sep 17 00:00:00 2001 From: tuoping Date: Thu, 22 Apr 2021 08:20:58 +0800 Subject: [PATCH 25/66] changed LICENSE to url; deleted whatsnew, application-examples and known_issues in index.rst --- LICENSE.rst => LICENSE | 0 doc/credits.rst | 42 +++++++++++++++++++++--------------------- doc/index.rst | 3 --- doc/license.rst | 4 +--- 4 files changed, 22 insertions(+), 27 deletions(-) rename LICENSE.rst => LICENSE (100%) diff --git a/LICENSE.rst b/LICENSE similarity index 100% rename from LICENSE.rst rename to LICENSE diff --git a/doc/credits.rst b/doc/credits.rst index a58d0b825c..d7f076fff3 100644 --- a/doc/credits.rst +++ b/doc/credits.rst @@ -5,28 +5,29 @@ Authors and Credits Core Package Contributors ========================= -* amcadmus -* AnguseZhang -* ass7798 -* DiracMD -* dongdawn -* felix5572 -* jameswind -* jiaweile -* jxxiaoshaoye -* kevinwenminion -* KuangYu -* lqs0609 -* marian-code -* njzjz -* robinzyb -* tansongchen +* Han Wang +* Jinzhe Zeng +* Marián Rynik +* denghuilu +* Denghui Lu +* Lu +* GeiduanLiu * tuoping -* Unboundwill -* Vibsteamer -* y1xiaoc +* ziyao +* Duo * YWolfeee +* marian-code * ZiyaoLi +* haidi +* Jiequn Han +* Yixiao Chen +* bwang-ecnu +* hlyang +* Linfeng Zhang +* deepmodeling +* iProzd +* njzjz +* wsyxbcl Other Credits ============= @@ -36,5 +37,4 @@ Other Credits (If you have contributed to the ``deepmd-kit`` core package and your name is missing, please send an email to the contributors, or -`open a pull request for this page `_ -in the `deepmd-kit repository `_) +open a pull request in the `deepmd-kit repository `_) diff --git a/doc/index.rst b/doc/index.rst index 63a4ffef5c..af24e4b091 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -18,9 +18,6 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r install getting-started tensorboard - whatsnew - application-examples - known_issues .. toctree:: :maxdepth: 2 diff --git a/doc/license.rst b/doc/license.rst index 9e36eb6946..366102905e 100644 --- a/doc/license.rst +++ b/doc/license.rst @@ -2,6 +2,4 @@ License ================== -The project DeePMD-kit is licensed under GNU LGPLv3.0. - -.. include:: ../LICENSE.rst +The project DeePMD-kit is licensed under `GNU LGPLv3.0 `_. From 45956f6193451ea2f60e45b4d3391f53f3d0ed0d Mon Sep 17 00:00:00 2001 From: tuoping Date: Thu, 22 Apr 2021 08:39:22 +0800 Subject: [PATCH 26/66] corrected subsection links --- doc/getting-started.md | 9 +++++---- doc/index.rst | 1 + 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/getting-started.md b/doc/getting-started.md index 1384ef7306..7dfa2a1fe0 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -3,14 +3,15 @@ In this text, we will call the deep neural network that is used to represent the 1. [Prepare data](#prepare-data) 2. [Train a model](#train-a-model) - - [The DeePMD model](#the-deepmd-model) - - [The DeepPot-SE model](#the-deeppot-se-model) + - [Write the input script](#write-the-input-script) + - [Training](#training) + - [Training analysis with Tensorboard](#training-analysis-with-tensorboard) 3. [Freeze a model](#freeze-a-model) 4. [Test a model](#test-a-model) 5. [Compress a model](#compress-a-model) 6. [Model inference](#model-inference) 7. [Run MD](#run-md) - - [Run MD with LAMMPS](#Run-MD-with-LAMMPS) + - [Run MD with LAMMPS](#run-md-with-lammps) - [Run path-integral MD with i-PI](#run-path-integral-md-with-i-pi) - [Use deep potential with ASE](#use-deep-potential-with-ase) @@ -78,7 +79,7 @@ One can use the a convenient tool `dpdata` to convert data directly from the out 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. DeePMD-kit implements the following descriptors: -1. [se_e2_a](train-se-e2-a): DeepPot-SE constructed from all information (both angular and radial) of atomic configurations. The embedding takes the distance between atoms as input. +1. [se_e2_a](train-se-e2-a#model): 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): DeepPot-SE constructed from radial information of atomic configurations. The embedding takes the distance between atoms as input. 3. [se_e3](train-se-e3): DeepPot-SE constructed from all information (both angular and radial) of atomic configurations. The embedding takes angles between two neighboring atoms as input. 4. loc_frame: Defines a local frame at each atom, and the compute the descriptor as local coordinates under this frame. diff --git a/doc/index.rst b/doc/index.rst index af24e4b091..86425931d7 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -18,6 +18,7 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r install getting-started tensorboard + troubleshooting .. toctree:: :maxdepth: 2 From c626b55b5b9456192389ed7cfef9b0e67c7c92c0 Mon Sep 17 00:00:00 2001 From: tuoping Date: Thu, 22 Apr 2021 08:43:34 +0800 Subject: [PATCH 27/66] testing external section links --- doc/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/getting-started.md b/doc/getting-started.md index 7dfa2a1fe0..15aa41be80 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -79,7 +79,7 @@ One can use the a convenient tool `dpdata` to convert data directly from the out 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. DeePMD-kit implements the following descriptors: -1. [se_e2_a](train-se-e2-a#model): DeepPot-SE constructed from all information (both angular and radial) of atomic configurations. The embedding takes the distance between atoms as input. +1. [se_e2_a](train-se-e2-a.md#model): 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): DeepPot-SE constructed from radial information of atomic configurations. The embedding takes the distance between atoms as input. 3. [se_e3](train-se-e3): DeepPot-SE constructed from all information (both angular and radial) of atomic configurations. The embedding takes angles between two neighboring atoms as input. 4. loc_frame: Defines a local frame at each atom, and the compute the descriptor as local coordinates under this frame. From 2f7c49cbbf700b76008b4b6ab4a303cccadc6480 Mon Sep 17 00:00:00 2001 From: tuoping Date: Thu, 22 Apr 2021 08:47:31 +0800 Subject: [PATCH 28/66] same --- doc/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/getting-started.md b/doc/getting-started.md index 15aa41be80..af4d2c4bf4 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -79,7 +79,7 @@ One can use the a convenient tool `dpdata` to convert data directly from the out 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. DeePMD-kit implements the following descriptors: -1. [se_e2_a](train-se-e2-a.md#model): DeepPot-SE constructed from all information (both angular and radial) of atomic configurations. The embedding takes the distance between atoms as input. +1. [se_e2_a](train-se-e2-a.html#model): 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): DeepPot-SE constructed from radial information of atomic configurations. The embedding takes the distance between atoms as input. 3. [se_e3](train-se-e3): DeepPot-SE constructed from all information (both angular and radial) of atomic configurations. The embedding takes angles between two neighboring atoms as input. 4. loc_frame: Defines a local frame at each atom, and the compute the descriptor as local coordinates under this frame. From 940d08dbf4c14cac7b20321eb446d76fadd4df78 Mon Sep 17 00:00:00 2001 From: tuoping Date: Thu, 22 Apr 2021 10:56:00 +0800 Subject: [PATCH 29/66] changed all the superlinks in getting-started.md from markdown format to html format --- doc/getting-started.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/getting-started.md b/doc/getting-started.md index af4d2c4bf4..0a2e409fcc 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -79,14 +79,14 @@ One can use the a convenient tool `dpdata` to convert data directly from the out 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. DeePMD-kit implements the following descriptors: -1. [se_e2_a](train-se-e2-a.html#model): 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): DeepPot-SE constructed from radial information of atomic configurations. The embedding takes the distance between atoms as input. -3. [se_e3](train-se-e3): DeepPot-SE constructed from all information (both angular and radial) of atomic configurations. The embedding takes angles between two neighboring atoms as input. -4. loc_frame: Defines a local frame at each atom, and the compute the descriptor as local coordinates under this frame. -5. [hybrid](train-hybrid): Concate a list of descriptors to form a new descriptor. +1. `se_e2_a`: 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`: DeepPot-SE constructed from radial information of atomic configurations. The embedding takes the distance between atoms as input. +3. `se_e3`: DeepPot-SE constructed from all information (both angular and radial) of atomic configurations. The embedding takes angles between two neighboring atoms as input. +4. `loc_frame`: Defines a local frame at each atom, and the compute the descriptor as local coordinates under this frame. +5. `hybrid`: Concate a list of descriptors to form a new descriptor. The fitting of the following physical properties are supported -1. [ener](train-se-e2-a.md): Fitting the energy of the system. The force (derivative with atom positions) and the virial (derivative with the box tensor) can also be trained. See [the example](train-se-e2-a.md). +1. `ener`: Fitting the energy of the system. The force (derivative with atom positions) and the virial (derivative with the box tensor) can also be trained. See the example. 2. dipole: The dipole moment. 3. polar: The polarizability. @@ -97,7 +97,7 @@ The training can be invoked by ```bash $ dp train input.json ``` -where `input.json` is the name of the input script. See [the example](train-se-e2-a.md) for more details. +where `input.json` is the name of the input script. See the example for more details. During the training, checkpoints will be written to files with prefix `save_ckpt` every `save_freq` training steps. From 563a7054a0fdd41fbf7794c48a1174ae91d53653 Mon Sep 17 00:00:00 2001 From: tuoping Date: Thu, 22 Apr 2021 11:03:09 +0800 Subject: [PATCH 30/66] same --- doc/getting-started.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/getting-started.md b/doc/getting-started.md index 0a2e409fcc..9d9e02fc96 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -87,8 +87,8 @@ DeePMD-kit implements the following descriptors: The fitting of the following physical properties are supported 1. `ener`: Fitting the energy of the system. The force (derivative with atom positions) and the virial (derivative with the box tensor) can also be trained. See the example. -2. dipole: The dipole moment. -3. polar: The polarizability. +2. `dipole`: The dipole moment. +3. `polar`: The polarizability. ### Training From a28afd5aca119a25dcde9fe4c75d84ab15d294f4 Mon Sep 17 00:00:00 2001 From: tuoping <80671886+tuoping@users.noreply.github.com> Date: Thu, 22 Apr 2021 04:16:51 -0500 Subject: [PATCH 31/66] Update doc/conf.py Do not use any in Python files. Co-authored-by: Jinzhe Zeng --- doc/conf.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index d3f25baf57..9a36c7ce99 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -31,7 +31,7 @@ extensions = [ 'recommonmark', "sphinx_rtd_theme", - 'sphinx_markdown_tables', + 'sphinx_markdown_tables', 'sphinx.ext.autosummary' ] @@ -60,4 +60,3 @@ autodoc_default_flags = ['members'] autosummary_generate = True master_doc = 'index' - From a9619bb2ff771eacb08244fa17dacb37c580cf16 Mon Sep 17 00:00:00 2001 From: tuoping <80671886+tuoping@users.noreply.github.com> Date: Thu, 22 Apr 2021 04:17:24 -0500 Subject: [PATCH 32/66] Update doc/getting-started.md Use a publish version instead Co-authored-by: Jinzhe Zeng --- doc/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/getting-started.md b/doc/getting-started.md index 9d9e02fc96..eb1e855944 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -369,4 +369,4 @@ dyn.run(fmax=1e-6) print(water.get_positions()) ``` [DP]:https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.143001 -[DP-SE]:https://arxiv.org/abs/1805.09003 +[DP-SE]:https://dl.acm.org/doi/10.5555/3327345.3327356 From b38d538c08bc73e93b9c5ee76564f72a04c2f122 Mon Sep 17 00:00:00 2001 From: tuoping Date: Thu, 22 Apr 2021 17:34:53 +0800 Subject: [PATCH 33/66] added some descriptor/scripts in api.rst; Changed the user names of contributors in credits.rst; Removed install-hardware-platforms; Put URL for GPLv2 in index.rst --- doc/api.rst | 18 +++++++++++++++- doc/credits.rst | 34 +++++++++++++++---------------- doc/index.rst | 2 +- doc/install-hardware-platforms.md | 3 --- doc/install.rst | 1 - 5 files changed, 34 insertions(+), 24 deletions(-) delete mode 100644 doc/install-hardware-platforms.md diff --git a/doc/api.rst b/doc/api.rst index f5a541cbf6..94cfca1dd6 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -41,11 +41,27 @@ API :members: :undoc-members: +.. automodule:: deepmd.descriptor.se_r + :members: + :undoc-members: + .. automodule:: deepmd.descriptor.se_ar :members: :undoc-members: -.. automodule:: deepmd.descriptor.se_r +.. automodule:: deepmd.descriptor.se_a_ebd + :members: + :undoc-members: + +.. automodule:: deepmd.descriptor.se_t + :members: + :undoc-members: + +.. automodule:: deepmd.descriptor.se_a_ef + :members: + :undoc-members: + +.. automodule:: deepmd.descriptor.se_hybrid :members: :undoc-members: diff --git a/doc/credits.rst b/doc/credits.rst index d7f076fff3..d2b21ecef9 100644 --- a/doc/credits.rst +++ b/doc/credits.rst @@ -5,29 +5,27 @@ Authors and Credits Core Package Contributors ========================= -* Han Wang -* Jinzhe Zeng -* Marián Rynik -* denghuilu -* Denghui Lu -* Lu -* GeiduanLiu +* amacadmus +* AnguseZhang * tuoping -* ziyao -* Duo +* denghuilu +* frankhan91 * YWolfeee -* marian-code +* njzjz * ZiyaoLi -* haidi -* Jiequn Han -* Yixiao Chen -* bwang-ecnu -* hlyang -* Linfeng Zhang -* deepmodeling +* zhouwei25 +* JiabinYang +* y1xiaoc * iProzd -* njzjz +* gzq942560379 +* marian-code +* hsulab +* bwang-ecnu +* GeiduanLiu +* haidi-ustc +* hlyang1992 * wsyxbcl +* frankhan91 Other Credits ============= diff --git a/doc/index.rst b/doc/index.rst index 86425931d7..2b21363735 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -9,7 +9,7 @@ DeePMD-kit's documentation 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. -.. Important:: The project DeePMD-kit is licensed under GNU LGPLv3.0. If you use this code in any future publications, please cite this using *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.* +.. Important:: The project DeePMD-kit is licensed under `GNU LGPLv3.0 `_. If you use this code in any future publications, please cite this using *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.* .. toctree:: :maxdepth: 2 diff --git a/doc/install-hardware-platforms.md b/doc/install-hardware-platforms.md deleted file mode 100644 index f326544b33..0000000000 --- a/doc/install-hardware-platforms.md +++ /dev/null @@ -1,3 +0,0 @@ - -# Installation on different hardware platforms - diff --git a/doc/install.rst b/doc/install.rst index 03b18cd5ee..1a59c1668b 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -6,5 +6,4 @@ Installation install-easy install-source - install-hardware-platforms From 006e7d1e0872acbd3d3c41566a54d0b5d2b045bd Mon Sep 17 00:00:00 2001 From: tuoping Date: Sat, 24 Apr 2021 15:24:39 +0800 Subject: [PATCH 34/66] Changed parser from recommonmark to myst, so the header-anchors in getting-started can support both markdown and html links. --- doc/api.rst | 2 +- doc/conf.py | 13 +++++++++++-- doc/getting-started.md | 12 ++++++------ doc/install-easy.md | 6 +++--- 4 files changed, 21 insertions(+), 12 deletions(-) diff --git a/doc/api.rst b/doc/api.rst index 94cfca1dd6..64c3f416e3 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -61,7 +61,7 @@ API :members: :undoc-members: -.. automodule:: deepmd.descriptor.se_hybrid +.. automodule:: deepmd.descriptor.hybrid :members: :undoc-members: diff --git a/doc/conf.py b/doc/conf.py index 9a36c7ce99..6e36749fdb 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -28,13 +28,22 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. +# extensions = [ +# 'recommonmark', +# "sphinx_rtd_theme", +# 'myst_parser', +# 'sphinx_markdown_tables', +# 'sphinx.ext.autosummary' +# ] + extensions = [ - 'recommonmark', "sphinx_rtd_theme", - 'sphinx_markdown_tables', + 'myst_parser', 'sphinx.ext.autosummary' ] +myst_heading_anchors = 4 + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/doc/getting-started.md b/doc/getting-started.md index eb1e855944..a1134b7fe6 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -79,14 +79,14 @@ One can use the a convenient tool `dpdata` to convert data directly from the out 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. DeePMD-kit implements the following descriptors: -1. `se_e2_a`: 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`: DeepPot-SE constructed from radial information of atomic configurations. The embedding takes the distance between atoms as input. -3. `se_e3`: DeepPot-SE constructed from all information (both angular and radial) of atomic configurations. The embedding takes angles between two neighboring atoms as input. +1. [`se_e2_a`](train-se-e2-a.md#descriptor): 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. 4. `loc_frame`: Defines a local frame at each atom, and the compute the descriptor as local coordinates under this frame. -5. `hybrid`: Concate a list of descriptors to form a new descriptor. +5. [`hybrid`](train-hybrid.md): Concate a list of descriptors to form a new descriptor. The fitting of the following physical properties are supported -1. `ener`: Fitting the energy of the system. The force (derivative with atom positions) and the virial (derivative with the box tensor) can also be trained. See the example. +1. [`ener`](train-se-e2-a.md#fitting): Fitting the energy of the system. The force (derivative with atom positions) and the virial (derivative with the box tensor) can also be trained. See [the example](train-se-e2-a.md#loss). 2. `dipole`: The dipole moment. 3. `polar`: The polarizability. @@ -97,7 +97,7 @@ The training can be invoked by ```bash $ dp train input.json ``` -where `input.json` is the name of the input script. See the example for more details. +where `input.json` is the name of the input script. See [the example](train-se-e2-a.md#train-a-deep-potential-model) for more details. During the training, checkpoints will be written to files with prefix `save_ckpt` every `save_freq` training steps. diff --git a/doc/install-easy.md b/doc/install-easy.md index 59ac040685..0b04e5f5b0 100644 --- a/doc/install-easy.md +++ b/doc/install-easy.md @@ -4,9 +4,9 @@ There various easy methods to install DeePMD-kit. Choose one that you prefer. If After your easy installation, DeePMD-kit (`dp`) and LAMMPS (`lmp`) will be available to execute. You can try `dp -h` and `lmp -h` to see the help. `mpirun` is also available considering you may want to run LAMMPS in parallel. -- [Install off-line packages](#Install-off-line-packages) -- [Install with conda](#Install-with-conda) -- [Install with docker](#Install-with-docker) +- [Install off-line packages](#install-off-line-packages) +- [Install with conda](#install-with-conda) +- [Install with docker](#install-with-docker) ## Install off-line packages From 40c6ae2a70b8aa6eb2c3e64dd928d63efa7e4083 Mon Sep 17 00:00:00 2001 From: tuoping Date: Sat, 24 Apr 2021 15:55:46 +0800 Subject: [PATCH 35/66] add myst-parser in requirements --- doc/requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/requirements.txt b/doc/requirements.txt index 1d39662bb4..21a5320b7e 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1 +1,2 @@ .[docs,cpu] +myst-parser From f0bdb8bfbcbdb34dbb0e09510284a0cb3d035415 Mon Sep 17 00:00:00 2001 From: tuoping Date: Sun, 25 Apr 2021 09:01:27 +0800 Subject: [PATCH 36/66] move doc dependence packages from requirements.txt to setup.py --- doc/requirements.txt | 1 - requirements.txt | 1 - setup.py | 2 +- 3 files changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/requirements.txt b/doc/requirements.txt index 21a5320b7e..1d39662bb4 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,2 +1 @@ .[docs,cpu] -myst-parser diff --git a/requirements.txt b/requirements.txt index 3fc6ded104..0bbdf12005 100644 --- a/requirements.txt +++ b/requirements.txt @@ -4,4 +4,3 @@ pyyaml dargs >= 0.2.2 tqdm typing_extensions -sphinx_markdown_tables diff --git a/setup.py b/setup.py index 5f7f2fa8bc..70aa026248 100644 --- a/setup.py +++ b/setup.py @@ -107,7 +107,7 @@ cmake_minimum_required_version="3.0", extras_require={ "test": ["dpdata>=0.1.9", "ase", "pytest", "pytest-cov", "pytest-sugar"], - "docs": ["sphinx", "recommonmark", "sphinx_rtd_theme"], + "docs": ["sphinx", "recommonmark", "sphinx_rtd_theme", "sphinx_markdown_tables", "myst-parser"], **extras_require, }, entry_points={"console_scripts": ["dp = deepmd.entrypoints.main:main"]}, From dfc048482d25ae4da9d75512d30234bad8978aff Mon Sep 17 00:00:00 2001 From: tuoping Date: Mon, 26 Apr 2021 09:57:38 +0800 Subject: [PATCH 37/66] changed contributor's order in credits.rst --- doc/credits.rst | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/doc/credits.rst b/doc/credits.rst index d2b21ecef9..f58e1f69e8 100644 --- a/doc/credits.rst +++ b/doc/credits.rst @@ -7,25 +7,24 @@ Core Package Contributors * amacadmus * AnguseZhang -* tuoping * denghuilu -* frankhan91 -* YWolfeee -* njzjz -* ZiyaoLi -* zhouwei25 -* JiabinYang -* y1xiaoc -* iProzd -* gzq942560379 -* marian-code -* hsulab * bwang-ecnu +* frankhan91 * GeiduanLiu +* gzq942560379 * haidi-ustc * hlyang1992 +* hsulab +* iProzd +* JiabinYang +* marian-code +* njzjz +* tuoping * wsyxbcl -* frankhan91 +* y1xiaoc +* YWolfeee +* zhouwei25 +* ZiyaoLi Other Credits ============= From c60523fa5b332a35d99c28c597dfcdf0ddb8c861 Mon Sep 17 00:00:00 2001 From: tuoping Date: Mon, 26 Apr 2021 11:37:42 +0800 Subject: [PATCH 38/66] change whatsnew --- doc/index.rst | 1 + doc/whatsnew.md | 25 ++++++++----------------- 2 files changed, 9 insertions(+), 17 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 2b21363735..b8250b2a47 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -18,6 +18,7 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r install getting-started tensorboard + whatsnew troubleshooting .. toctree:: diff --git a/doc/whatsnew.md b/doc/whatsnew.md index 113837e7e4..3b893380e0 100644 --- a/doc/whatsnew.md +++ b/doc/whatsnew.md @@ -1,17 +1,8 @@ -# What's New -## Type embedding -Instead of training embedding net for each atom pair (regard as G_ij, and turns out to be N^2 networks), we now share a public embedding net (regard as G) and present each atom with a special vector, named as type embedding (v_i). So, our algorithm for generating a description change from G_ij(s_ij) to G(s_ij, v_i, v_j). -1. We obtain the type embedding by a small embedding net, projecting atom type to embedding vector. -2. As for the fitting net, we fix the type embedding and replace individual fitting net with shared fitting net. (while adding type embedding information to its input) - -### Training hyper-parameter -descriptor: -"type" : "se_a_ebd" # for applying share embedding algorithm -"type_filter" : list # network architecture of the small embedding net, which output type embedding -"type_one_side" : bool # when generating descriptor, whether use the centric atom type embedding (true: G(s_ij, v_i, v_j), false: G(s_ij, v_j)) - -fitting_net: -"share_fitting" : bool # if applying share fitting net, set true - - -## Interpolation with tabulated pair potentials +# What's new in DeePMD-kit v2.0 +* [Model compression](getting-started.md#compress-a-model). Accelerate the efficiency of model inference for 4-15 times. +* [New descriptors](getting-started.md#write-the-input-script). Including [`se_e2_r`](train-se-e2-r.md) and [`se_e3`](train-se-e3.md). +* [Hybridization of descriptors](train-hybrid.md). Hybrid descriptor constructed from concatenation of several descriptors. +* Atom type embedding. +* Training and inference the dipole (vector) and polarizability (matrix). +* Split of training and validation dataset. +* Optimized training on GPUs. From fa48bebbe437e1aeddea364ef50d419f0aff24bf Mon Sep 17 00:00:00 2001 From: tuoping Date: Tue, 27 Apr 2021 13:09:02 +0800 Subject: [PATCH 39/66] change highlights in 2.0 in README.md --- README.md | 11 +---------- doc/{whatsnew.md => highlights.md} | 2 +- doc/index.rst | 2 +- 3 files changed, 3 insertions(+), 12 deletions(-) rename doc/{whatsnew.md => highlights.md} (94%) diff --git a/README.md b/README.md index a70644f9b3..485661ae5d 100644 --- a/README.md +++ b/README.md @@ -19,16 +19,7 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r For more information, check the [documentation](https://deepmd.readthedocs.io/). -## Highlights in DeePMD-kit v2.0 - -* [Model compression](doc/use-deepmd-kit.md#compress-a-model). Accelerate the efficiency of model inference for 4-15 times. -* [New descriptors](doc/use-deepmd-kit.md#write-the-input-script). Including [`se_e2_r`](doc/train-se-e2-r.md) and [`se_e3`](doc/train-se-e3.md). -* [Hybridization of descriptors](doc/train-hybrid.md). Hybrid descriptor constructed from concatenation of several descriptors. -* Atom type embedding. -* Training and inference the dipole (vector) and polarizability (matrix). -* Split of training and validation dataset. -* Optimized training on GPUs. - + ## Highlighted features * **interfaced with TensorFlow**, one of the most popular deep learning frameworks, making the training process highly automatic and efficient, in addition Tensorboard can be used to visualize training procedure. From ebb24196a7663dc6abf14ba11a9a44d60c8261e2 Mon Sep 17 00:00:00 2001 From: tuoping Date: Thu, 29 Apr 2021 15:27:05 +0800 Subject: [PATCH 41/66] Add CONTRIBUTING.md including "what you can contribute" "before you contribute": "overview of deepmd-kit" (branches) and "developer guide" (Link to "doc/development/index") "how to contribute": fork, clone, change, unittest, commit and PR Made directories troubleshooting and development, so that it's easier for everyone to PR. Added roadmap.md in doc to list optional commissions for future contributors. Removed highlights in doc, and added in README. Removed empty file known_issues.md --- CONTRIBUTING.md | 138 ++++++++++++++++++ README.md | 22 ++- doc/{ => development}/api.rst | 0 .../coding-conventions.rst} | 0 doc/development/index.rst | 7 + doc/highlights.md | 8 - doc/index.rst | 19 ++- doc/known_issues.md | 1 - doc/roadmap.md | 0 doc/troubleshooting.md | 37 ----- doc/troubleshooting/index.rst | 12 ++ doc/troubleshooting/installation.md | 17 +++ .../md-version-compatibility.md | 10 ++ doc/troubleshooting/model-compatability.md | 5 + 14 files changed, 220 insertions(+), 56 deletions(-) create mode 100644 CONTRIBUTING.md rename doc/{ => development}/api.rst (100%) rename doc/{developement.rst => development/coding-conventions.rst} (100%) create mode 100644 doc/development/index.rst delete mode 100644 doc/highlights.md delete mode 100644 doc/known_issues.md create mode 100644 doc/roadmap.md delete mode 100644 doc/troubleshooting.md create mode 100644 doc/troubleshooting/index.rst create mode 100644 doc/troubleshooting/installation.md create mode 100644 doc/troubleshooting/md-version-compatibility.md create mode 100644 doc/troubleshooting/model-compatability.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..714c825fb0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,138 @@ +# DeePMD-kit Contributing Guide + +Welcome to [DeePMD-kit](https://github.com/deepmodeling/deepmd-kit)! We are excited about the prospect of you joining [DeepModeling Community](https://github.com/deepmodeling/community/). + +## What you can contribute + +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 +- Implement a feature or add a patch, whatever you think deepmd-kit is missing +- Browse the deepmd-kit [roadmap](doc/roadmap.md) and pick a bug you want to smash or a feature you want to implement +See [here](#before-you-contribute) for some before-hand heads-up. +See [here](#how-to-contribute) to learn 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.) +- Fix or update inappropriate or outdated descriptions +- Add missing content (sentence, paragraph, or a new document) +- 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 + +### Developer guide +See [here](#doc/development/index) for coding conventions, API and other neads-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. See [here](https://git-scm.com/doc) if you want to really master git. + +### Step 1: Fork the repository + +1. Visit the project: +2. Click the **Fork** button on the top right and wait it to finish. + +### 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. + ``` + 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. + ``` + 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 + + # 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 + ``` + 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" + ``` + See [Commit Message Style](https://github.com/DeepModeling/community/blob/master/contributors/commit-message-pr-style.md#how-to-write-a-good-commit-message). + +5. Push the changed codes to your original repo on github. + ``` + git push origin devel + + ``` + +### Alternatively: Create a new branch + +1. Get your local master up-to-date with upstream/master. + + ``` + 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. + + ``` + git checkout -b new-branch-name + ``` + +3. Modify your codes and design unit tests. + +4. Commit your changes + + ``` + 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" + ``` + See [Commit Message Style](https://github.com/DeepModeling/community/blob/master/contributors/commit-message-pr-style.md#how-to-write-a-good-commit-message). + +5. Keep your branch in sync with upstream/master + + ``` + # While on your new branch + git fetch upstream + git rebase upstream/master + ``` + +6. Push your changes to the remote + + ``` + git push -u origin new-branch-name # "-u" is used to track the remote branch from origin + ``` + +### Step 3: Create a pull request + +1. Visit your fork at (replace `$username` with your GitHub ID) +2. Click `pull requests`, followed by `New pull request` and `Compare & pull request` to create your PR. See [Pull Request Title Style](https://github.com/DeepModeling/community/blob/master/contributors/commit-message-pr-style.md#pull-request-title-style). + +Now, your PR is successfully submitted! After this PR is merged, you will automatically become a contributor to DeePMD-kit. + +## Join us + +Join [DeepModeling Community](https://github.com/deepmodeling/community/)! diff --git a/README.md b/README.md index abc9a5ab98..90c70a122a 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,14 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r For more information, check the [documentation](https://deepmd.readthedocs.io/). - +# Heighlights in DeePMD-kit v2.0 +* [Model compression](getting-started.md#compress-a-model). Accelerate the efficiency of model inference for 4-15 times. +* [New descriptors](getting-started.md#write-the-input-script). Including [`se_e2_r`](train-se-e2-r.md) and [`se_e3`](train-se-e3.md). +* [Hybridization of descriptors](train-hybrid.md). Hybrid descriptor constructed from concatenation of several descriptors. +* Atom type embedding. +* Training and inference the dipole (vector) and polarizability (matrix). +* Split of training and validation dataset. +* Optimized training on GPUs. ## Highlighted features * **interfaced with TensorFlow**, one of the most popular deep learning frameworks, making the training process highly automatic and efficient, in addition Tensorboard can be used to visualize training procedure. @@ -88,13 +95,18 @@ The code is organized as follows: * `source/op`: tensorflow op implementation. working with library. - # Troubleshooting -See the [troubleshooting page](doc/troubleshooting.md). +See the [troubleshooting page](doc/troubleshooting/index.md). + + +# Contributing + +See [DeePMD-kit Documentation Contributing Guide](CONTRIBUTING.md) to become a contributor! 🤓 +Welcome to join [DeepModeling Community](https://github.com/deepmodeling/community/)! 🤓 [1]: http://www.global-sci.com/galley/CiCP-2017-0213.pdf [2]: https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.143001 -[3]:https://arxiv.org/abs/1805.09003 -[4]:https://aip.scitation.org/doi/full/10.1063/1.5027645 +[3]: https://arxiv.org/abs/1805.09003 +[4]: https://aip.scitation.org/doi/full/10.1063/1.5027645 diff --git a/doc/api.rst b/doc/development/api.rst similarity index 100% rename from doc/api.rst rename to doc/development/api.rst diff --git a/doc/developement.rst b/doc/development/coding-conventions.rst similarity index 100% rename from doc/developement.rst rename to doc/development/coding-conventions.rst diff --git a/doc/development/index.rst b/doc/development/index.rst new file mode 100644 index 0000000000..b3c6275eb4 --- /dev/null +++ b/doc/development/index.rst @@ -0,0 +1,7 @@ + +.. toctree:: + :maxdepth: 2 + :caption: Developer Guide + + coding-conventions + api diff --git a/doc/highlights.md b/doc/highlights.md deleted file mode 100644 index 6ab61ee8f3..0000000000 --- a/doc/highlights.md +++ /dev/null @@ -1,8 +0,0 @@ -# Heighlights in DeePMD-kit v2.0 -* [Model compression](getting-started.md#compress-a-model). Accelerate the efficiency of model inference for 4-15 times. -* [New descriptors](getting-started.md#write-the-input-script). Including [`se_e2_r`](train-se-e2-r.md) and [`se_e3`](train-se-e3.md). -* [Hybridization of descriptors](train-hybrid.md). Hybrid descriptor constructed from concatenation of several descriptors. -* Atom type embedding. -* Training and inference the dipole (vector) and polarizability (matrix). -* Split of training and validation dataset. -* Optimized training on GPUs. diff --git a/doc/index.rst b/doc/index.rst index bb53fb66f7..f38e0c6689 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -11,6 +11,8 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r .. Important:: The project DeePMD-kit is licensed under `GNU LGPLv3.0 `_. If you use this code in any future publications, please cite this using *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.* +.. _user-guide: + .. toctree:: :maxdepth: 2 :caption: User Guide @@ -18,8 +20,10 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r install getting-started tensorboard - highlights - troubleshooting + troubleshooting/index + + +.. _data-and-parameters: .. toctree:: :maxdepth: 2 @@ -28,12 +32,17 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r data-conv train-input + +.. _developer-guide: + .. toctree:: :maxdepth: 2 - :caption: Programmer Guide + :caption: Developer Guide - developement - api + development/index + + +.. _project-details: .. toctree:: :maxdepth: 2 diff --git a/doc/known_issues.md b/doc/known_issues.md deleted file mode 100644 index c050fb20b1..0000000000 --- a/doc/known_issues.md +++ /dev/null @@ -1 +0,0 @@ -# Nuts and Bolts diff --git a/doc/roadmap.md b/doc/roadmap.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/doc/troubleshooting.md b/doc/troubleshooting.md deleted file mode 100644 index afdcdf9985..0000000000 --- a/doc/troubleshooting.md +++ /dev/null @@ -1,37 +0,0 @@ -# Troubleshooting -In consequence of various differences of computers or systems, problems may occur. Some common circumstances are listed as follows. -If other unexpected problems occur, you're welcome to contact us for help. - -## Model compatability - -When the version of DeePMD-kit used to training model is different from the that of DeePMD-kit running MDs, one has the problem of model compatability. - -DeePMD-kit guarantees that the codes with the same major and minor revisions are compatible. That is to say v0.12.5 is compatible to v0.12.0, but is not compatible to v0.11.0 nor v1.0.0. - -## Installation: inadequate versions of gcc/g++ -Sometimes you may use a gcc/g++ of version <4.9. If you have a gcc/g++ of version > 4.9, say, 7.2.0, you may choose to use it by doing -```bash -export CC=/path/to/gcc-7.2.0/bin/gcc -export CXX=/path/to/gcc-7.2.0/bin/g++ -``` - -If, for any reason, for example, you only have a gcc/g++ of version 4.8.5, you can still compile all the parts of TensorFlow and most of the parts of DeePMD-kit. i-Pi will be disabled automatically. - -## Installation: build files left in DeePMD-kit -When you try to build a second time when installing DeePMD-kit, files produced before may contribute to failure. Thus, you may clear them by -```bash -cd build -rm -r * -``` -and redo the `cmake` process. - -## MD: cannot run LAMMPS after installing a new version of DeePMD-kit -This typically happens when you install a new version of DeePMD-kit and copy directly the generated `USER-DEEPMD` to a LAMMPS source code folder and re-install LAMMPS. - -To solve this problem, it suffices to first remove `USER-DEEPMD` from LAMMPS source code by -```bash -make no-user-deepmd -``` -and then install the new `USER-DEEPMD`. - -If this does not solve your problem, try to decompress the LAMMPS source tarball and install LAMMPS from scratch again, which typically should be very fast. diff --git a/doc/troubleshooting/index.rst b/doc/troubleshooting/index.rst new file mode 100644 index 0000000000..35627f5945 --- /dev/null +++ b/doc/troubleshooting/index.rst @@ -0,0 +1,12 @@ +Troubleshooting +============== + +In consequence of various differences of computers or systems, problems may occur. Some common circumstances are listed as follows. +If other unexpected problems occur, you're welcome to contact us for help. + +.. toctree:: + :maxdepth: 2 + + installation.md + md-version-compatibility.md + model-compatability.md diff --git a/doc/troubleshooting/installation.md b/doc/troubleshooting/installation.md new file mode 100644 index 0000000000..6b2a7caf3f --- /dev/null +++ b/doc/troubleshooting/installation.md @@ -0,0 +1,17 @@ +# Installation +## Inadequate versions of gcc/g++ +Sometimes you may use a gcc/g++ of version <4.9. If you have a gcc/g++ of version > 4.9, say, 7.2.0, you may choose to use it by doing +```bash +export CC=/path/to/gcc-7.2.0/bin/gcc +export CXX=/path/to/gcc-7.2.0/bin/g++ +``` + +If, for any reason, for example, you only have a gcc/g++ of version 4.8.5, you can still compile all the parts of TensorFlow and most of the parts of DeePMD-kit. i-Pi will be disabled automatically. + +## Build files left in DeePMD-kit +When you try to build a second time when installing DeePMD-kit, files produced before may contribute to failure. Thus, you may clear them by +```bash +cd build +rm -r * +``` +and redo the `cmake` process. diff --git a/doc/troubleshooting/md-version-compatibility.md b/doc/troubleshooting/md-version-compatibility.md new file mode 100644 index 0000000000..dfc2e3abc2 --- /dev/null +++ b/doc/troubleshooting/md-version-compatibility.md @@ -0,0 +1,10 @@ +# MD: cannot run LAMMPS after installing a new version of DeePMD-kit +This typically happens when you install a new version of DeePMD-kit and copy directly the generated `USER-DEEPMD` to a LAMMPS source code folder and re-install LAMMPS. + +To solve this problem, it suffices to first remove `USER-DEEPMD` from LAMMPS source code by +```bash +make no-user-deepmd +``` +and then install the new `USER-DEEPMD`. + +If this does not solve your problem, try to decompress the LAMMPS source tarball and install LAMMPS from scratch again, which typically should be very fast. diff --git a/doc/troubleshooting/model-compatability.md b/doc/troubleshooting/model-compatability.md new file mode 100644 index 0000000000..3ae1338cc9 --- /dev/null +++ b/doc/troubleshooting/model-compatability.md @@ -0,0 +1,5 @@ +# Model compatability + +When the version of DeePMD-kit used to training model is different from the that of DeePMD-kit running MDs, one has the problem of model compatability. + +DeePMD-kit guarantees that the codes with the same major and minor revisions are compatible. That is to say v0.12.5 is compatible to v0.12.0, but is not compatible to v0.11.0 nor v1.0.0. From 990f1cb0579b6392ca318fa128f78a364ddfbff5 Mon Sep 17 00:00:00 2001 From: tuoping Date: Thu, 29 Apr 2021 18:31:18 +0800 Subject: [PATCH 42/66] Fixed some minor mistakes. PS: All the links to repo community are futile yet. --- CONTRIBUTING.md | 8 +++++--- README.md | 7 ++++--- doc/roadmap.md | 1 + 3 files changed, 10 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 714c825fb0..a984b405ec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,8 +12,10 @@ You can start from any one of the following items to help improve deepmd-kit - Smash a bug - Implement a feature or add a patch, whatever you think deepmd-kit is missing - Browse the deepmd-kit [roadmap](doc/roadmap.md) and pick a bug you want to smash or a feature you want to implement + See [here](#before-you-contribute) for some before-hand heads-up. -See [here](#how-to-contribute) to learn to contribute. + +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): @@ -36,10 +38,10 @@ Currently, we maintain two main branch: - devel : branch for developers ### Developer guide -See [here](#doc/development/index) for coding conventions, API and other neads-to-know of the code. +See [here](doc/development/index) for coding conventions, API and other neads-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. See [here](https://git-scm.com/doc) if you want to really master git. +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 diff --git a/README.md b/README.md index 90c70a122a..4a8c51f099 100644 --- a/README.md +++ b/README.md @@ -97,13 +97,14 @@ The code is organized as follows: # Troubleshooting -See the [troubleshooting page](doc/troubleshooting/index.md). +See the [troubleshooting page](doc/troubleshooting/index.rst). # Contributing -See [DeePMD-kit Documentation Contributing Guide](CONTRIBUTING.md) to become a contributor! 🤓 -Welcome to join [DeepModeling Community](https://github.com/deepmodeling/community/)! 🤓 +See [DeePMD-kit Contributing Guide](CONTRIBUTING.md) to become a contributor! 🤓 + +You are welcome to join [DeepModeling Community](https://github.com/deepmodeling/community/)! 🤓 [1]: http://www.global-sci.com/galley/CiCP-2017-0213.pdf diff --git a/doc/roadmap.md b/doc/roadmap.md index e69de29bb2..437766dd8f 100644 --- a/doc/roadmap.md +++ b/doc/roadmap.md @@ -0,0 +1 @@ +# Roadmap From 18c00a2c80981e37c1abadd357707447cfeee1c5 Mon Sep 17 00:00:00 2001 From: tuoping Date: Thu, 29 Apr 2021 19:25:20 +0800 Subject: [PATCH 43/66] changed document for training inputs from train-input.rst to train-input-auto.rst (train-input.rst is basically emplty). --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4a8c51f099..dcfcf16cb0 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ The typical procedure of using DeePMD-kit includes 5 steps A quick-start on using DeePMD-kit can be found [here](doc/use-deepmd-kit.md). -A full [document](doc/train-input.rst) on options in the training input script is available. +A full [document](doc/train-input-auto.rst) on options in the training input script is available. # Code structure From fe084a340c7fd39113a70ab28a1ecb8cc89fb07f Mon Sep 17 00:00:00 2001 From: tuoping <80671886+tuoping@users.noreply.github.com> Date: Fri, 30 Apr 2021 07:02:10 -0500 Subject: [PATCH 44/66] Fixed links under "highlights in kit2.0.0". --- README.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index dcfcf16cb0..b736831b99 100644 --- a/README.md +++ b/README.md @@ -20,9 +20,9 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r For more information, check the [documentation](https://deepmd.readthedocs.io/). # Heighlights in DeePMD-kit v2.0 -* [Model compression](getting-started.md#compress-a-model). Accelerate the efficiency of model inference for 4-15 times. -* [New descriptors](getting-started.md#write-the-input-script). Including [`se_e2_r`](train-se-e2-r.md) and [`se_e3`](train-se-e3.md). -* [Hybridization of descriptors](train-hybrid.md). Hybrid descriptor constructed from concatenation of several descriptors. +* [Model compression](doc/getting-started.md#compress-a-model). Accelerate the efficiency of model inference for 4-15 times. +* [New descriptors](doc/getting-started.md#write-the-input-script). Including [`se_e2_r`](doc/train-se-e2-r.md) and [`se_e3`](doc/train-se-e3.md). +* [Hybridization of descriptors](doc/train-hybrid.md). Hybrid descriptor constructed from concatenation of several descriptors. * Atom type embedding. * Training and inference the dipole (vector) and polarizability (matrix). * Split of training and validation dataset. @@ -97,15 +97,13 @@ The code is organized as follows: # Troubleshooting -See the [troubleshooting page](doc/troubleshooting/index.rst). +See the [troubleshooting page](doc/troubleshooting/index.md). # Contributing See [DeePMD-kit Contributing Guide](CONTRIBUTING.md) to become a contributor! 🤓 -You are welcome to join [DeepModeling Community](https://github.com/deepmodeling/community/)! 🤓 - [1]: http://www.global-sci.com/galley/CiCP-2017-0213.pdf [2]: https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.143001 From 9c2115efaa82945e7016154fad45bfe72b4e02b8 Mon Sep 17 00:00:00 2001 From: tuoping Date: Mon, 3 May 2021 18:50:03 +0800 Subject: [PATCH 45/66] Checked all the links, and made sure they work both in markdown mode and html mode. Especially the ones in README.md and CONTRIBUTING.md --- CONTRIBUTING.md | 16 ++---- README.md | 18 +++--- doc/conf.py | 45 ++++++++++++++- doc/development/index.md | 4 ++ doc/development/index.rst | 7 --- doc/install-easy.md | 39 ------------- doc/{install-source.md => install.md} | 62 ++++++++++++++++++--- doc/install.rst | 9 --- doc/roadmap.md | 1 - doc/troubleshooting/{index.rst => index.md} | 13 ++--- 10 files changed, 121 insertions(+), 93 deletions(-) create mode 100644 doc/development/index.md delete mode 100644 doc/development/index.rst delete mode 100644 doc/install-easy.md rename doc/{install-source.md => install.md} (74%) delete mode 100644 doc/install.rst delete mode 100644 doc/roadmap.md rename doc/troubleshooting/{index.rst => index.md} (57%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a984b405ec..e63b2807e8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # DeePMD-kit Contributing Guide -Welcome to [DeePMD-kit](https://github.com/deepmodeling/deepmd-kit)! We are excited about the prospect of you joining [DeepModeling Community](https://github.com/deepmodeling/community/). +Welcome to [DeePMD-kit](https://github.com/deepmodeling/deepmd-kit)! ## What you can contribute @@ -11,7 +11,7 @@ You can start from any one of the following items to help improve deepmd-kit - Smash a bug - Implement a feature or add a patch, whatever you think deepmd-kit is missing -- Browse the deepmd-kit [roadmap](doc/roadmap.md) and pick a bug you want to smash or a feature you want to implement +- Browse [issues](https://github.com/deepmodeling/deepmd-kit/issues), find an issue labeled enhancement or bug, and help to solve it. See [here](#before-you-contribute) for some before-hand heads-up. @@ -78,12 +78,10 @@ Please perform the following steps to create your Pull Request to this repositor 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" ``` - See [Commit Message Style](https://github.com/DeepModeling/community/blob/master/contributors/commit-message-pr-style.md#how-to-write-a-good-commit-message). - + 5. Push the changed codes to your original repo on github. ``` git push origin devel - ``` ### Alternatively: Create a new branch @@ -112,7 +110,6 @@ Please perform the following steps to create your Pull Request to this repositor 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" ``` - See [Commit Message Style](https://github.com/DeepModeling/community/blob/master/contributors/commit-message-pr-style.md#how-to-write-a-good-commit-message). 5. Keep your branch in sync with upstream/master @@ -131,10 +128,9 @@ Please perform the following steps to create your Pull Request to this repositor ### Step 3: Create a pull request 1. Visit your fork at (replace `$username` with your GitHub ID) -2. Click `pull requests`, followed by `New pull request` and `Compare & pull request` to create your PR. See [Pull Request Title Style](https://github.com/DeepModeling/community/blob/master/contributors/commit-message-pr-style.md#pull-request-title-style). +2. Click `pull requests`, followed by `New pull request` and `Compare & pull request` to create your PR. Now, your PR is successfully submitted! After this PR is merged, you will automatically become a contributor to DeePMD-kit. -## Join us - -Join [DeepModeling Community](https://github.com/deepmodeling/community/)! +## Contact us +E-mail: contact@deepmodeling.org \ No newline at end of file diff --git a/README.md b/README.md index b736831b99..4a94f34fc5 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ # Table of contents - [About DeePMD-kit](#about-deepmd-kit) - - [Highlights in v2.0](#highlights-in-deepmd-kit-v2.0) + - [Highlights in v2.0](#heighlights-in-deepmd-kit-v2.0) - [Highlighted features](#highlighted-features) - [License and credits](#license-and-credits) - [Deep Potential in a nutshell](#deep-potential-in-a-nutshell) @@ -62,15 +62,15 @@ One may manually install DeePMD-kit by following the instuctions on [installing The typical procedure of using DeePMD-kit includes 5 steps -1. [Prepare data](doc/use-deepmd-kit.md#prepare-data) -2. [Train a model](doc/use-deepmd-kit.md#train-a-model) +1. [Prepare data](doc/getting-started.md#prepare-data) +2. [Train a model](doc/getting-started.md#train-a-model) 3. [Analyze training with Tensorboard](doc/tensorboard.md) -4. [Freeze the model](doc/use-deepmd-kit.md#freeze-a-model) -5. [Test the model](doc/use-deepmd-kit.md#test-a-model) -6. [Compress the model](doc/use-deepmd-kit.md#compress-a-model) -7. [Inference the model in python](doc/use-deepmd-kit.md#model-inference) or using the model in other molecular simulation packages like [LAMMPS](doc/use-deepmd-kit.md#run-md-with-lammps), [i-PI](doc/use-deepmd-kit.md#run-path-integral-md-with-i-pi) or [ASE](doc/use-deepmd-kit.md#use-deep-potential-with-ase). +4. [Freeze the model](doc/getting-started.md#freeze-a-model) +5. [Test the model](doc/getting-started.md#test-a-model) +6. [Compress the model](doc/getting-started.md#compress-a-model) +7. [Inference the model in python](doc/getting-started.md#model-inference) or using the model in other molecular simulation packages like [LAMMPS](doc/getting-started.md#run-md-with-lammps), [i-PI](doc/getting-started.md#run-path-integral-md-with-i-pi) or [ASE](doc/getting-started.md#use-deep-potential-with-ase). -A quick-start on using DeePMD-kit can be found [here](doc/use-deepmd-kit.md). +A quick-start on using DeePMD-kit can be found [here](doc/getting-started.md). A full [document](doc/train-input-auto.rst) on options in the training input script is available. @@ -105,7 +105,7 @@ See the [troubleshooting page](doc/troubleshooting/index.md). See [DeePMD-kit Contributing Guide](CONTRIBUTING.md) to become a contributor! 🤓 -[1]: http://www.global-sci.com/galley/CiCP-2017-0213.pdf +[1]: https://arxiv.org/abs/1707.01478 [2]: https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.143001 [3]: https://arxiv.org/abs/1805.09003 [4]: https://aip.scitation.org/doi/full/10.1063/1.5027645 diff --git a/doc/conf.py b/doc/conf.py index 6e36749fdb..98227474d1 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -10,11 +10,51 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os +import os # import sys import recommonmark from recommonmark.transform import AutoStructify +def mkindex_troubleshooting(): + oldfindex = open("troubleshooting/index.md", "r") + _oldlist = oldfindex.readlines() + oldlist = _oldlist[4:] + oldfindex.close() + + newfindex = open("troubleshooting/index.md", "a") + for root, dirs, files in os.walk("./troubleshooting/", topdown=False): + for name in files: + if (name == "index.md"): + continue + if (name[-3:] == ".md"): + longname = "- ["+name[:-3]+"]("+name+")\n" + if (longname not in oldlist): + newfindex.write(longname) + + newfindex.close() + +def mkindex_development(): + oldfindex = open("development/index.md", "r") + _oldlist = oldfindex.readlines() + oldlist = _oldlist[2:] + oldfindex.close() + + newfindex = open("development/index.md", "a") + for root, dirs, files in os.walk("./development/", topdown=False): + for name in files: + if (name == "index.md"): + continue + if (name[-3:] == ".md"): + longname = "- ["+name[:-3]+"]("+name+")\n" + if (longname not in oldlist): + newfindex.write(longname) + else: + if (name[-4:] == ".rst"): + longname = "- ["+name[:-4]+"]("+name+")\n" + if (longname not in oldlist): + newfindex.write(longname) + + newfindex.close() # -- Project information ----------------------------------------------------- @@ -36,6 +76,9 @@ # 'sphinx.ext.autosummary' # ] +mkindex_troubleshooting() +mkindex_development() + extensions = [ "sphinx_rtd_theme", 'myst_parser', diff --git a/doc/development/index.md b/doc/development/index.md new file mode 100644 index 0000000000..a2ac5eb7e2 --- /dev/null +++ b/doc/development/index.md @@ -0,0 +1,4 @@ +# Developer Guide + +- [coding-conventions](coding-conventions.rst) +- [api](api.rst) diff --git a/doc/development/index.rst b/doc/development/index.rst deleted file mode 100644 index b3c6275eb4..0000000000 --- a/doc/development/index.rst +++ /dev/null @@ -1,7 +0,0 @@ - -.. toctree:: - :maxdepth: 2 - :caption: Developer Guide - - coding-conventions - api diff --git a/doc/install-easy.md b/doc/install-easy.md deleted file mode 100644 index 0b04e5f5b0..0000000000 --- a/doc/install-easy.md +++ /dev/null @@ -1,39 +0,0 @@ -# Easy installation methods - -There various easy methods to install DeePMD-kit. Choose one that you prefer. If you want to build by yourself, jump to the next two sections. - -After your easy installation, DeePMD-kit (`dp`) and LAMMPS (`lmp`) will be available to execute. You can try `dp -h` and `lmp -h` to see the help. `mpirun` is also available considering you may want to run LAMMPS in parallel. - -- [Install off-line packages](#install-off-line-packages) -- [Install with conda](#install-with-conda) -- [Install with docker](#install-with-docker) - - -## Install off-line packages -Both CPU and GPU version offline packages are avaiable in [the Releases page](https://github.com/deepmodeling/deepmd-kit/releases). - -## Install with conda -DeePMD-kit is avaiable with [conda](https://github.com/conda/conda). Install [Anaconda](https://www.anaconda.com/distribution/#download-section) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html) first. - -To install the CPU version: -```bash -conda install deepmd-kit=*=*cpu lammps-dp=*=*cpu -c deepmodeling -``` - -To install the GPU version containing [CUDA 10.1](https://docs.nvidia.com/deploy/cuda-compatibility/index.html#binary-compatibility__table-toolkit-driver): -```bash -conda install deepmd-kit=*=*gpu lammps-dp=*=*gpu -c deepmodeling -``` - -## Install with docker -A docker for installing the DeePMD-kit is available [here](https://github.com/orgs/deepmodeling/packages/container/package/deepmd-kit). - -To pull the CPU version: -```bash -docker pull ghcr.io/deepmodeling/deepmd-kit:1.3.1_cpu -``` - -To pull the GPU version: -```bash -docker pull ghcr.io/deepmodeling/deepmd-kit:1.3.1_cuda10.1_gpu -``` diff --git a/doc/install-source.md b/doc/install.md similarity index 74% rename from doc/install-source.md rename to doc/install.md index 6c4da81ceb..7eca440dee 100644 --- a/doc/install-source.md +++ b/doc/install.md @@ -1,4 +1,50 @@ -# Install from source code +# Installation + +- [Easy installation methods](#easy-installation-methods) +- [Install from source code](#install-from-source-code) + +## Easy installation methods + +There various easy methods to install DeePMD-kit. Choose one that you prefer. If you want to build by yourself, jump to the next two sections. + +After your easy installation, DeePMD-kit (`dp`) and LAMMPS (`lmp`) will be available to execute. You can try `dp -h` and `lmp -h` to see the help. `mpirun` is also available considering you may want to run LAMMPS in parallel. + +- [Install off-line packages](#install-off-line-packages) +- [Install with conda](#install-with-conda) +- [Install with docker](#install-with-docker) + + +### Install off-line packages +Both CPU and GPU version offline packages are avaiable in [the Releases page](https://github.com/deepmodeling/deepmd-kit/releases). + +### Install with conda +DeePMD-kit is avaiable with [conda](https://github.com/conda/conda). Install [Anaconda](https://www.anaconda.com/distribution/#download-section) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html) first. + +To install the CPU version: +```bash +conda install deepmd-kit=*=*cpu lammps-dp=*=*cpu -c deepmodeling +``` + +To install the GPU version containing [CUDA 10.1](https://docs.nvidia.com/deploy/cuda-compatibility/index.html#binary-compatibility__table-toolkit-driver): +```bash +conda install deepmd-kit=*=*gpu lammps-dp=*=*gpu -c deepmodeling +``` + +### Install with docker +A docker for installing the DeePMD-kit is available [here](https://github.com/orgs/deepmodeling/packages/container/package/deepmd-kit). + +To pull the CPU version: +```bash +docker pull ghcr.io/deepmodeling/deepmd-kit:2.0.0_cpu +``` + +To pull the GPU version: +```bash +docker pull ghcr.io/deepmodeling/deepmd-kit:2.0.0_cuda10.1_gpu +``` + + +## Install from source code 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). @@ -23,8 +69,8 @@ deepmd_source_dir=`pwd` - [Install LAMMPS's DeePMD-kit module](#install-lammpss-deepmd-kit-module) -## Install the python interface -### Install the Tensorflow's python interface +### Install the python interface +#### Install the Tensorflow's python interface First, check the python version on your machine ```bash python --version @@ -59,7 +105,7 @@ python -c "import tensorflow as tf;print(tf.reduce_sum(tf.random.normal([1000, 1 ``` One should remember to activate the virtual environment every time he/she uses deepmd-kit. -### Install the DeePMD-kit's python interface +#### Install the DeePMD-kit's python interface Execute ```bash @@ -91,11 +137,11 @@ Valid subcommands: test test the model ``` -## Install the C++ interface +### Install the C++ interface If one does not need to use DeePMD-kit with Lammps or I-Pi, then the python interface installed in the previous section does everything and he/she can safely skip this section. -### Install the Tensorflow's C++ interface +#### Install the Tensorflow's C++ interface Check the compiler version on your machine @@ -107,7 +153,7 @@ The C++ interface of DeePMD-kit was tested with compiler gcc >= 4.8. It is notic First the C++ interface of Tensorflow should be installed. It is noted that the version of Tensorflow should be in consistent with the python interface. You may follow [the instruction](install-tf.2.3.md) to install the corresponding C++ interface. -### Install the DeePMD-kit's C++ interface +#### Install the DeePMD-kit's C++ interface Now goto the source code directory of DeePMD-kit and make a build place. ```bash @@ -136,7 +182,7 @@ $ ls $deepmd_root/lib libdeepmd_ipi.so libdeepmd_op.so libdeepmd.so ``` -## Install LAMMPS's DeePMD-kit module +### Install LAMMPS's DeePMD-kit module DeePMD-kit provide module for running MD simulation with LAMMPS. Now make the DeePMD-kit module for LAMMPS. ```bash cd $deepmd_source_dir/source/build diff --git a/doc/install.rst b/doc/install.rst deleted file mode 100644 index 1a59c1668b..0000000000 --- a/doc/install.rst +++ /dev/null @@ -1,9 +0,0 @@ -Installation -============== - -.. toctree:: - :maxdepth: 2 - - install-easy - install-source - diff --git a/doc/roadmap.md b/doc/roadmap.md deleted file mode 100644 index 437766dd8f..0000000000 --- a/doc/roadmap.md +++ /dev/null @@ -1 +0,0 @@ -# Roadmap diff --git a/doc/troubleshooting/index.rst b/doc/troubleshooting/index.md similarity index 57% rename from doc/troubleshooting/index.rst rename to doc/troubleshooting/index.md index 35627f5945..04e7b31812 100644 --- a/doc/troubleshooting/index.rst +++ b/doc/troubleshooting/index.md @@ -1,12 +1,7 @@ -Troubleshooting -============== - +# Troubleshooting In consequence of various differences of computers or systems, problems may occur. Some common circumstances are listed as follows. If other unexpected problems occur, you're welcome to contact us for help. - -.. toctree:: - :maxdepth: 2 - installation.md - md-version-compatibility.md - model-compatability.md +- [installation](installation.md) +- [md-version-compatibility](md-version-compatibility.md) +- [model-compatability](model-compatability.md) From 74269c0f7486c09e27dd0e55f2dd71f07cad99ad Mon Sep 17 00:00:00 2001 From: tuoping Date: Mon, 3 May 2021 19:10:03 +0800 Subject: [PATCH 46/66] Sorry, fixed a broken link in CONTRIBUTING.md. --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e63b2807e8..79ed149809 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,7 +38,7 @@ Currently, we maintain two main branch: - devel : branch for developers ### Developer guide -See [here](doc/development/index) for coding conventions, API and other neads-to-know of the code. +See [here](doc/development/index.md) for coding conventions, API and other neads-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. From 2bd50a6a119dc6c74af173c727b39dd834518c31 Mon Sep 17 00:00:00 2001 From: tuoping Date: Thu, 6 May 2021 09:59:36 +0800 Subject: [PATCH 47/66] Asigned language 'bash' for codes in CONTRIBUTING.md; Corrected a typo in README.md --- CONTRIBUTING.md | 20 ++++++++++---------- README.md | 2 +- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 79ed149809..3a7f90ac1b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,7 +51,7 @@ 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 @@ -59,7 +59,7 @@ Please perform the following steps to create your Pull Request to this repositor ``` 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". @@ -73,14 +73,14 @@ Please perform the following steps to create your Pull Request to this repositor 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" ``` 5. Push the changed codes to your original repo on github. - ``` + ```bash git push origin devel ``` @@ -88,7 +88,7 @@ Please perform the following steps to create your Pull Request to this repositor 1. Get your local master up-to-date with upstream/master. - ``` + ```bash cd $working_dir/deepmd-kit git fetch upstream git checkout master @@ -97,7 +97,7 @@ Please perform the following steps to create your Pull Request to this repositor 2. Create a new branch based on the master branch. - ``` + ```bash git checkout -b new-branch-name ``` @@ -105,7 +105,7 @@ Please perform the following steps to create your Pull Request to this repositor 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" @@ -113,7 +113,7 @@ Please perform the following steps to create your Pull Request to this repositor 5. Keep your branch in sync with upstream/master - ``` + ```bash # While on your new branch git fetch upstream git rebase upstream/master @@ -121,7 +121,7 @@ Please perform the following steps to create your Pull Request to this repositor 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 ``` @@ -133,4 +133,4 @@ 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 \ No newline at end of file +E-mail: contact@deepmodeling.org diff --git a/README.md b/README.md index 4a94f34fc5..8d9f93d67e 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r For more information, check the [documentation](https://deepmd.readthedocs.io/). -# Heighlights in DeePMD-kit v2.0 +# Highlights in DeePMD-kit v2.0 * [Model compression](doc/getting-started.md#compress-a-model). Accelerate the efficiency of model inference for 4-15 times. * [New descriptors](doc/getting-started.md#write-the-input-script). Including [`se_e2_r`](doc/train-se-e2-r.md) and [`se_e3`](doc/train-se-e3.md). * [Hybridization of descriptors](doc/train-hybrid.md). Hybrid descriptor constructed from concatenation of several descriptors. From ea0acb753d19528100bb70ce7c4bc4cb57a56652 Mon Sep 17 00:00:00 2001 From: Han Wang Date: Sat, 8 May 2021 08:46:25 +0800 Subject: [PATCH 48/66] Update CONTRIBUTING.md --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3a7f90ac1b..86199588d7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,7 +38,7 @@ Currently, we maintain two main branch: - devel : branch for developers ### Developer guide -See [here](doc/development/index.md) for coding conventions, API and other neads-to-know of the code. +See [here](doc/development/index.md) 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. From 671be8de9c7d13d94681bf32f041636bec8d863c Mon Sep 17 00:00:00 2001 From: Han Wang Date: Sat, 8 May 2021 09:03:59 +0800 Subject: [PATCH 49/66] fix typo in README.md Co-authored-by: Jinzhe Zeng --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8d9f93d67e..5939997aa9 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ # Table of contents - [About DeePMD-kit](#about-deepmd-kit) - - [Highlights in v2.0](#heighlights-in-deepmd-kit-v2.0) + - [Highlights in v2.0](#highlights-in-deepmd-kit-v2.0) - [Highlighted features](#highlighted-features) - [License and credits](#license-and-credits) - [Deep Potential in a nutshell](#deep-potential-in-a-nutshell) From e7a05893394bf337ba550d78a2e17ca86d58d9a1 Mon Sep 17 00:00:00 2001 From: Han Wang Date: Sat, 8 May 2021 09:22:53 +0800 Subject: [PATCH 50/66] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5939997aa9..162603099a 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ One may manually install DeePMD-kit by following the instuctions on [installing # Use DeePMD-kit -The typical procedure of using DeePMD-kit includes 5 steps +The typical procedure of using DeePMD-kit includes the following steps 1. [Prepare data](doc/getting-started.md#prepare-data) 2. [Train a model](doc/getting-started.md#train-a-model) From 3735a8fdcc80317a2b5ecc0952561845f2389b64 Mon Sep 17 00:00:00 2001 From: Han Wang Date: Sat, 8 May 2021 09:26:56 +0800 Subject: [PATCH 51/66] Update credits.rst Not all contributors are core contributor --- doc/credits.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/credits.rst b/doc/credits.rst index f58e1f69e8..0db2b58f80 100644 --- a/doc/credits.rst +++ b/doc/credits.rst @@ -2,7 +2,7 @@ Authors and Credits ******************* -Core Package Contributors +Package Contributors ========================= * amacadmus From 383cfa9139d4eacfc31643df378f508ca12a4540 Mon Sep 17 00:00:00 2001 From: tuoping Date: Wed, 12 May 2021 16:03:06 +0800 Subject: [PATCH 52/66] Changed entries in troubleshooting/index.md and development/index.md from filenames to the headlines in each file; added [Do we need to set rcut < half boxsize ?](rcut.md) in troubleshooting; added [The temperature undulates violently during early stages of MD](md-energy-undulation.md) in troubleshooting. --- doc/conf.py | 53 +++++++++++++++------ doc/development/index.md | 6 ++- doc/troubleshooting/index.md | 14 ++++-- doc/troubleshooting/md-energy-undulation.md | 5 ++ doc/troubleshooting/rcut.md | 7 +++ 5 files changed, 65 insertions(+), 20 deletions(-) create mode 100644 doc/troubleshooting/md-energy-undulation.md create mode 100644 doc/troubleshooting/rcut.md diff --git a/doc/conf.py b/doc/conf.py index 98227474d1..26a2f0758c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -17,9 +17,13 @@ def mkindex_troubleshooting(): oldfindex = open("troubleshooting/index.md", "r") - _oldlist = oldfindex.readlines() - oldlist = _oldlist[4:] + oldlist = oldfindex.readlines() oldfindex.close() + + oldnames = [] + for entry in oldlist: + _name = entry[entry.find("(")+1 : entry.find(")")] + oldnames.append(_name) newfindex = open("troubleshooting/index.md", "a") for root, dirs, files in os.walk("./troubleshooting/", topdown=False): @@ -27,35 +31,54 @@ def mkindex_troubleshooting(): if (name == "index.md"): continue if (name[-3:] == ".md"): - longname = "- ["+name[:-3]+"]("+name+")\n" - if (longname not in oldlist): + if (name not in oldnames): + f = open("./troubleshooting/"+name, "r") + _headline = f.readlines()[0] + headline = _headline[1:].strip() + longname = "["+headline+"]"+"("+name+")\n\n" newfindex.write(longname) + newfindex.close() + def mkindex_development(): oldfindex = open("development/index.md", "r") - _oldlist = oldfindex.readlines() - oldlist = _oldlist[2:] + oldlist = oldfindex.readlines() oldfindex.close() + + oldnames = [] + for entry in oldlist: + _name = entry[entry.find("(")+1 : entry.find(")")] + oldnames.append(_name) newfindex = open("development/index.md", "a") for root, dirs, files in os.walk("./development/", topdown=False): for name in files: if (name == "index.md"): continue - if (name[-3:] == ".md"): - longname = "- ["+name[:-3]+"]("+name+")\n" - if (longname not in oldlist): - newfindex.write(longname) - else: - if (name[-4:] == ".rst"): - longname = "- ["+name[:-4]+"]("+name+")\n" - if (longname not in oldlist): - newfindex.write(longname) + if (name not in oldnames): + if (name[-3:] == ".md"): + f = open("./development/"+name, "r") + _headline = f.readlines()[0] + headline = _headline[1:].strip() + else: + if (name[-4:] == ".rst"): + f = open("./development/"+name, "r") + _lines = f.readlines() + for _headline in _lines: + headline = _headline.strip() + if (len(headline) == 0): + continue + if (headline[0] != "." and headline[0] != "="): + break + longname = "["+headline+"]"+"("+name+")\n\n" + newfindex.write(longname) + newfindex.close() + # -- Project information ----------------------------------------------------- project = 'DeePMD-kit' diff --git a/doc/development/index.md b/doc/development/index.md index a2ac5eb7e2..04077fa174 100644 --- a/doc/development/index.md +++ b/doc/development/index.md @@ -1,4 +1,6 @@ # Developer Guide -- [coding-conventions](coding-conventions.rst) -- [api](api.rst) +[API](api.rst) + +[Coding Conventions](coding-conventions.rst) + diff --git a/doc/troubleshooting/index.md b/doc/troubleshooting/index.md index 04e7b31812..93ab80ee53 100644 --- a/doc/troubleshooting/index.md +++ b/doc/troubleshooting/index.md @@ -2,6 +2,14 @@ In consequence of various differences of computers or systems, problems may occur. Some common circumstances are listed as follows. If other unexpected problems occur, you're welcome to contact us for help. -- [installation](installation.md) -- [md-version-compatibility](md-version-compatibility.md) -- [model-compatability](model-compatability.md) + +[Installation](installation.md) + +[MD: cannot run LAMMPS after installing a new version of DeePMD-kit](md-version-compatibility.md) + +[Model compatability](model-compatability.md) + +[The temperature undulates violently during early stages of MD](md-energy-undulation.md) + +[Do we need to set rcut < half boxsize ?](rcut.md) + diff --git a/doc/troubleshooting/md-energy-undulation.md b/doc/troubleshooting/md-energy-undulation.md new file mode 100644 index 0000000000..f45a21cd72 --- /dev/null +++ b/doc/troubleshooting/md-energy-undulation.md @@ -0,0 +1,5 @@ +# The temperature undulates violently during early stages of MD + +This is probably because your structure is too far from the equlibrium configuration. + +Although, to make sure the potential model is truly accurate, we recommend to check model deviation. diff --git a/doc/troubleshooting/rcut.md b/doc/troubleshooting/rcut.md new file mode 100644 index 0000000000..ffc023079b --- /dev/null +++ b/doc/troubleshooting/rcut.md @@ -0,0 +1,7 @@ +# Do we need to set rcut < half boxsize ? + +When seeking the neighbors of atom i under periodic boundary condition, deepmd-kit considers all j atoms within cutoff Rc from atom i in all mirror cells. + +So, no, so there is no limitation on the setting of rcut. + +PS: The reason why some softwares require rcut < half boxsize is that they only consider the nearest mirrors from the center cell. Deepmd-kit is totally different from them. From e1cda0236f24fd700d373c7e01e940d41b387e43 Mon Sep 17 00:00:00 2001 From: tuoping Date: Wed, 12 May 2021 16:43:05 +0800 Subject: [PATCH 53/66] Optimized the mkindex function in conf.py --- doc/conf.py | 70 ++++++++++-------------------------- doc/troubleshooting/index.md | 4 +-- 2 files changed, 20 insertions(+), 54 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 26a2f0758c..be5d261907 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -15,8 +15,9 @@ import recommonmark from recommonmark.transform import AutoStructify -def mkindex_troubleshooting(): - oldfindex = open("troubleshooting/index.md", "r") +def mkindex(dirname): + dirname = dirname + "/" + oldfindex = open(dirname + "index.md", "r") oldlist = oldfindex.readlines() oldfindex.close() @@ -25,55 +26,20 @@ def mkindex_troubleshooting(): _name = entry[entry.find("(")+1 : entry.find(")")] oldnames.append(_name) - newfindex = open("troubleshooting/index.md", "a") - for root, dirs, files in os.walk("./troubleshooting/", topdown=False): - for name in files: - if (name == "index.md"): - continue - if (name[-3:] == ".md"): - if (name not in oldnames): - f = open("./troubleshooting/"+name, "r") - _headline = f.readlines()[0] - headline = _headline[1:].strip() - longname = "["+headline+"]"+"("+name+")\n\n" - newfindex.write(longname) - - - newfindex.close() - - -def mkindex_development(): - oldfindex = open("development/index.md", "r") - oldlist = oldfindex.readlines() - oldfindex.close() - - oldnames = [] - for entry in oldlist: - _name = entry[entry.find("(")+1 : entry.find(")")] - oldnames.append(_name) - - newfindex = open("development/index.md", "a") - for root, dirs, files in os.walk("./development/", topdown=False): - for name in files: - if (name == "index.md"): - continue - if (name not in oldnames): - if (name[-3:] == ".md"): - f = open("./development/"+name, "r") - _headline = f.readlines()[0] - headline = _headline[1:].strip() + newfindex = open(dirname + "index.md", "a") + for root, dirs, files in os.walk(dirname, topdown=False): + newnames = [name for name in files if name != "index.md" and name not in oldnames] + for name in newnames: + f = open(dirname + name, "r") + _lines = f.readlines() + for _headline in _lines: + headline = _headline.strip() + if (len(headline) == 0 or headline[0] == "." or headline[0] == "="): + continue else: - if (name[-4:] == ".rst"): - f = open("./development/"+name, "r") - _lines = f.readlines() - for _headline in _lines: - headline = _headline.strip() - if (len(headline) == 0): - continue - if (headline[0] != "." and headline[0] != "="): - break - longname = "["+headline+"]"+"("+name+")\n\n" - newfindex.write(longname) + break + longname = "["+headline+"]"+"("+name+")\n\n" + newfindex.write(longname) newfindex.close() @@ -99,8 +65,8 @@ def mkindex_development(): # 'sphinx.ext.autosummary' # ] -mkindex_troubleshooting() -mkindex_development() +mkindex("troubleshooting") +mkindex("development") extensions = [ "sphinx_rtd_theme", diff --git a/doc/troubleshooting/index.md b/doc/troubleshooting/index.md index 93ab80ee53..6c4e310557 100644 --- a/doc/troubleshooting/index.md +++ b/doc/troubleshooting/index.md @@ -9,7 +9,7 @@ If other unexpected problems occur, you're welcome to contact us for help. [Model compatability](model-compatability.md) -[The temperature undulates violently during early stages of MD](md-energy-undulation.md) +[# The temperature undulates violently during early stages of MD](md-energy-undulation.md) -[Do we need to set rcut < half boxsize ?](rcut.md) +[# Do we need to set rcut < half boxsize ?](rcut.md) From d9db26ff8db436df3179a295d68f303a976b6098 Mon Sep 17 00:00:00 2001 From: tuoping Date: Wed, 12 May 2021 17:00:29 +0800 Subject: [PATCH 54/66] Debuged conf.py --- doc/conf.py | 1 + doc/troubleshooting/index.md | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index be5d261907..65df5f063c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -33,6 +33,7 @@ def mkindex(dirname): f = open(dirname + name, "r") _lines = f.readlines() for _headline in _lines: + _headline = _headline.strip("#") headline = _headline.strip() if (len(headline) == 0 or headline[0] == "." or headline[0] == "="): continue diff --git a/doc/troubleshooting/index.md b/doc/troubleshooting/index.md index 6c4e310557..93ab80ee53 100644 --- a/doc/troubleshooting/index.md +++ b/doc/troubleshooting/index.md @@ -9,7 +9,7 @@ If other unexpected problems occur, you're welcome to contact us for help. [Model compatability](model-compatability.md) -[# The temperature undulates violently during early stages of MD](md-energy-undulation.md) +[The temperature undulates violently during early stages of MD](md-energy-undulation.md) -[# Do we need to set rcut < half boxsize ?](rcut.md) +[Do we need to set rcut < half boxsize ?](rcut.md) From 9d54f351297eae7751706a7464e0305566bc82f9 Mon Sep 17 00:00:00 2001 From: tuoping Date: Fri, 14 May 2021 08:42:36 +0800 Subject: [PATCH 55/66] Itemized presentation in troubleshooting/index.md and development/index.md; fixed typos in troubleshooting/rcut.md --- doc/conf.py | 2 +- doc/development/index.md | 6 ++---- doc/troubleshooting/index.md | 15 +++++---------- doc/troubleshooting/rcut.md | 6 +++--- 4 files changed, 11 insertions(+), 18 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 65df5f063c..824503f8b6 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -39,7 +39,7 @@ def mkindex(dirname): continue else: break - longname = "["+headline+"]"+"("+name+")\n\n" + longname = "- ["+headline+"]"+"("+name+")\n" newfindex.write(longname) diff --git a/doc/development/index.md b/doc/development/index.md index 04077fa174..cbc2135878 100644 --- a/doc/development/index.md +++ b/doc/development/index.md @@ -1,6 +1,4 @@ # Developer Guide -[API](api.rst) - -[Coding Conventions](coding-conventions.rst) - +- [API](api.rst) +- [Coding Conventions](coding-conventions.rst) diff --git a/doc/troubleshooting/index.md b/doc/troubleshooting/index.md index 93ab80ee53..0db7b82198 100644 --- a/doc/troubleshooting/index.md +++ b/doc/troubleshooting/index.md @@ -3,13 +3,8 @@ In consequence of various differences of computers or systems, problems may occu If other unexpected problems occur, you're welcome to contact us for help. -[Installation](installation.md) - -[MD: cannot run LAMMPS after installing a new version of DeePMD-kit](md-version-compatibility.md) - -[Model compatability](model-compatability.md) - -[The temperature undulates violently during early stages of MD](md-energy-undulation.md) - -[Do we need to set rcut < half boxsize ?](rcut.md) - +- [Installation](installation.md) +- [The temperature undulates violently during early stages of MD](md-energy-undulation.md) +- [MD: cannot run LAMMPS after installing a new version of DeePMD-kit](md-version-compatibility.md) +- [Model compatability](model-compatability.md) +- [Do we need to set rcut < half boxsize ?](rcut.md) diff --git a/doc/troubleshooting/rcut.md b/doc/troubleshooting/rcut.md index ffc023079b..147df0782b 100644 --- a/doc/troubleshooting/rcut.md +++ b/doc/troubleshooting/rcut.md @@ -1,7 +1,7 @@ # Do we need to set rcut < half boxsize ? -When seeking the neighbors of atom i under periodic boundary condition, deepmd-kit considers all j atoms within cutoff Rc from atom i in all mirror cells. +When seeking the neighbors of atom i under periodic boundary condition, deepmd-kit considers all j atoms within cutoff Rcut from atom i in all mirror cells. -So, no, so there is no limitation on the setting of rcut. +So, no, so there is no limitation on the setting of Rcut. -PS: The reason why some softwares require rcut < half boxsize is that they only consider the nearest mirrors from the center cell. Deepmd-kit is totally different from them. +PS: The reason why some softwares require Rcut < half boxsize is that they only consider the nearest mirrors from the center cell. Deepmd-kit is totally different from them. From 1b0b96b8222e1a6b7bb6d419a1977b5061909fb9 Mon Sep 17 00:00:00 2001 From: tuoping Date: Fri, 21 May 2021 17:01:07 +0800 Subject: [PATCH 56/66] Added doc for netsize setting; Added doc about how to specify the num of nodes used by a job. Added doc for sel setting Moved rcut.md to howtoset_rcut.md. Added classify_index_TS in conf.py to make two subsections in troubleshooting/index.md: "## Trouble shooting" and "## Parameter setting" --- doc/conf.py | 59 ++++++++- doc/troubleshooting/howtoset_netsize.md | 139 ++++++++++++++++++++++ doc/troubleshooting/howtoset_num_nodes.md | 16 +++ doc/troubleshooting/howtoset_rcut.md | 7 ++ doc/troubleshooting/howtoset_sel.md | 15 +++ doc/troubleshooting/index.md | 12 +- doc/troubleshooting/rcut.md | 7 -- 7 files changed, 244 insertions(+), 11 deletions(-) create mode 100644 doc/troubleshooting/howtoset_netsize.md create mode 100644 doc/troubleshooting/howtoset_num_nodes.md create mode 100644 doc/troubleshooting/howtoset_rcut.md create mode 100644 doc/troubleshooting/howtoset_sel.md delete mode 100644 doc/troubleshooting/rcut.md diff --git a/doc/conf.py b/doc/conf.py index 824503f8b6..71488ac4e0 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -28,7 +28,7 @@ def mkindex(dirname): newfindex = open(dirname + "index.md", "a") for root, dirs, files in os.walk(dirname, topdown=False): - newnames = [name for name in files if name != "index.md" and name not in oldnames] + newnames = [name for name in files if "index.md" not in name and name not in oldnames] for name in newnames: f = open(dirname + name, "r") _lines = f.readlines() @@ -45,6 +45,62 @@ def mkindex(dirname): newfindex.close() +def classify_index_TS(): + dirname = "troubleshooting/" + oldfindex = open(dirname + "index.md", "r") + oldlist = oldfindex.readlines() + oldfindex.close() + + oldnames = [] + sub_titles = [] + heads = [] + while(len(oldlist) > 0): + entry = oldlist.pop(0) + if (entry.find("(") >= 0): + _name = entry[entry.find("(")+1 : entry.find(")")] + oldnames.append(_name) + continue + if (entry.find("##") >= 0): + _name = entry[entry.find("##")+3:-1] + sub_titles.append(_name) + continue + entry.strip() + if (entry != '\n'): + heads.append(entry) + + newfindex = open(dirname + "index.md", "w") + for entry in heads: + newfindex.write(entry) + newfindex.write('\n') + sub_lists = [[],[]] + for root, dirs, files in os.walk(dirname, topdown=False): + newnames = [name for name in files if "index.md" not in name] + for name in newnames: + f = open(dirname + name, "r") + _lines = f.readlines() + f.close() + for _headline in _lines: + _headline = _headline.strip("#") + headline = _headline.strip() + if (len(headline) == 0 or headline[0] == "." or headline[0] == "="): + continue + else: + break + longname = "- ["+headline+"]"+"("+name+")\n" + if ("howtoset_" in name): + sub_lists[1].append(longname) + else: + sub_lists[0].append(longname) + + newfindex.write("## Trouble shooting\n") + for entry in sub_lists[0]: + newfindex.write(entry) + newfindex.write("\n") + newfindex.write("## Parameters setting\n") + for entry in sub_lists[1]: + newfindex.write(entry) + newfindex.close() + # -- Project information ----------------------------------------------------- @@ -68,6 +124,7 @@ def mkindex(dirname): mkindex("troubleshooting") mkindex("development") +classify_index_TS() extensions = [ "sphinx_rtd_theme", diff --git a/doc/troubleshooting/howtoset_netsize.md b/doc/troubleshooting/howtoset_netsize.md new file mode 100644 index 0000000000..93c981e2e4 --- /dev/null +++ b/doc/troubleshooting/howtoset_netsize.md @@ -0,0 +1,139 @@ +# How to tune Fitting/embedding-net size ? + +Here are some test forms on fitting-net size tuning or embedding-net size tuning performed on several different systems. + + +## Al2O3 + +### Fitting net size tuning form on Al2O3: (embedding-net size: [25,50,100]) + +Fitting-net size | Energy L2err(eV) | Energy L2err/Natoms(eV) | Force L2err(eV/Angstrom) +---|---|---|--- +[240,240,240] | 1.742252e-02 | 7.259383e-05 | 4.014115e-02 +[80,80,80] | 1.799349e-02 | 7.497287e-05 | 4.042977e-02 +[40,40,40] | 1.799036e-02 | 7.495984e-05 | 4.068806e-02 +[20,20,20] | 1.834032e-02 | 7.641801e-05 | 4.094784e-02 +[10,10,10] | 1.913058e-02 | 7.971073e-05 | 4.154775e-02 +[5,5,5] | 1.932914e-02 | 8.053808e-05 | 4.188052e-02 +[4,4,4] | 1.944832e-02 | 8.103467e-05 | 4.217826e-02 +[3,3,3] | 2.068631e-02 | 8.619296e-05 | 4.300497e-02 +[2,2,2] | 2.267962e-02 | 9.449840e-05 | 4.413609e-02 +[1,1,1] | 2.813596e-02 | 1.172332e-04 | 4.781115e-02 +[] | 3.135002e-02 | 1.306251e-04 | 5.373120e-02 + +### Embedding net size tuning form on Al2O3: (Fitting-net size: [240,240,240]) + +Embedding-net size | Energy L2err(eV) | Energy L2err/Natoms(eV) | Force L2err(eV/Angstrom) +---|---|---|--- +[25,50,100] | 1.742252e-02 | 7.259383e-05 | 4.014115e-02 +[10,20,40] | 2.909990e-02 | 1.212496e-04 | 4.734667e-02 +[5,10,20] | 3.357767e-02 | 1.399070e-04 | 5.706385e-02 +[4,8,16] | 6.060367e-02 | 2.525153e-04 | 7.333304e-02 +[3,6,12] | 5.656043e-02 | 2.356685e-04 | 7.793539e-02 +[2,4,8] | 5.277023e-02 | 2.198759e-04 | 7.459995e-02 +[1,2,4] | 1.302282e-01 | 5.426174e-04 | 9.672238e-02 + + +## Cu + +### Fitting net size tuning form on Cu: (embedding-net size: [25,50,100]) + +Fitting-net size | Energy L2err(eV) | Energy L2err/Natoms(eV) | Force L2err(eV/Angstrom) +---|---|---|--- +[240,240,240] | 4.135548e-02 | 1.615449e-04 | 8.940946e-02 +[20,20,20] | 4.323858e-02 | 1.689007e-04 | 8.955762e-02 +[10,10,10] | 4.399364e-02 | 1.718502e-04 | 8.962891e-02 +[5,5,5] | 4.468404e-02 | 1.745470e-04 | 8.970111e-02 +[4,4,4] | 4.463580e-02 | 1.743586e-04 | 8.972011e-02 +[3,3,3] | 4.493758e-02 | 1.755374e-04 | 8.971303e-02 +[2,2,2] | 4.500736e-02 | 1.758100e-04 | 8.973878e-02 +[1,1,1] | 4.542073e-02 | 1.774247e-04 | 8.964761e-02 +[] | 4.545168e-02 | 1.775456e-04 | 8.983201e-02 + +### Embedding net size tuning form on Cu: (Fitting-net size: [240,240,240]) + +Embedding-net size | Energy L2err(eV) | Energy L2err/Natoms(eV) | Force L2err(eV/Angstrom) +---|---|---|--- +[25,50,100] | 4.135548e-02 | 1.615449e-04 | 8.940946e-02 +[20,40,80] | 4.203562e-02 | 1.642016e-04 | 8.925881e-02 +[15,30,60] | 4.146672e-02 | 1.619794e-04 | 8.936911e-02 +[10,20,40] | 4.263060e-02 | 1.665258e-04 | 8.955818e-02 +[5,10,20] | 4.994913e-02 | 1.951138e-04 | 9.007786e-02 +[4,8,16] | 1.022157e-01 | 3.992802e-04 | 9.532119e-02 +[3,9,12] | 1.362098e-01 | 5.320695e-04 | 1.073860e-01 +[2,4,8] | 7.061800e-02 | 2.758515e-04 | 9.126418e-02 +[1,2,4] && seed = 1 | 9.843161e-02 | 3.844985e-04 | 9.348505e-02 +[1,2,4] && seed = 2 | 9.404335e-02 | 3.673568e-04 | 9.304089e-02 +[1,2,4] && seed = 3 | 1.508016e-01 | 5.890688e-04 | 1.382356e-01 +[1,2,4] && seed = 4 | 9.686949e-02 | 3.783965e-04 | 9.294820e-02 + + +## Water + +### Fitting net size tuning form on water: (embedding-net size: [25,50,100]) + +Fitting-net size | Energy L2err/Natoms(eV) | Force L2err(eV/Angstrom) +---|---|--- +[240,240,240] | 9.1589E-04 | 5.1540E-02 +[200,200,200] | 9.3221E-04 | 5.2366E-02 +[160,160,160] | 9.4274E-04 | 5.3403E-02 +[120,120,120] | 9.5407E-04 | 5.3093E-02 +[80,80,80] | 9.4605E-04 | 5.3402E-02 +[40,40,40] | 9.8533E-04 | 5.5790E-02 +[20,20,20] | 1.0057E-03 | 5.8232E-02 +[10,10,10] | 1.0466E-03 | 6.2279E-02 +[5,5,5] | 1.1154E-03 | 6.7994E-02 +[4,4,4] | 1.1289E-03 | 6.9613E-02 +[3,3,3] | 1.2368E-03 | 7.9786E-02 +[2,2,2] | 1.3558E-03 | 9.7042E-02 +[1,1,1] | 1.4633E-03 | 1.1265E-01 +[] | 1.5193E-03 | 1.2136E-01 + +### Embedding net size tuning form on water: (Fitting-net size: [240,240,240]) + +Embedding-net size | Energy L2err/Natoms(eV) | Force L2err(eV/Angstrom) +---|---|--- +[25,50,100] | 9.1589E-04 | 5.1540E-02 +[20,40,80] | 9.5080E-04 | 5.3593E-02 +[15,30,60] | 9.7996E-04 | 5.6338E-02 +[10,20,40] | 1.0353E-03 | 6.2776E-02 +[5,10,20] | 1.1254E-03 | 7.3195E-02 +[4,8,16] | 1.2495E-03 | 8.0371E-02 +[3,6,12] | 1.3604E-03 | 9.9883E-02 +[2,4,8] | 1.4358E-03 | 9.7389E-02 +[1,2,4] | 2.1765E-03 | 1.7276E-01 + + +## Mg-Al + +### Fitting net size tuning form on Mg-Al: (embedding-net size: [25,50,100]) + +Fitting-net size | Energy L2err/Natoms(eV) | Force L2err(eV/Angstrom) +---|---|--- +[240,240,240] | 3.9606e-03 | 1.6289e-02 +[200,200,200] | 3.9449e-03 | 1.6471e-02 +[160,160,160] | 4.0947e-03 | 1.6413e-02 +[120,120,120] | 3.9234e-03 | 1.6283e-02 +[80,80,80] | 3.9758e-03 | 1.6506e-02 +[40,40,40] | 3.9142e-03 | 1.6348e-02 +[20,20,20] | 4.1302e-03 | 1.7006e-02 +[10,10,10] | 4.3433e-03 | 1.7524e-02 +[5,5,5] | 5.3154e-03 | 1.9716e-02 +[4,4,4] | 5.4210e-03 | 1.9710e-02 +[2,2,2] | 6.2667e-03 | 2.2568e-02 +[1,1,1] | 7.3676e-03 | 2.6375e-02 +[] | 7.3999e-03 | 2.6097e-02 + +### Embedding net size tuning form on Mg-Al: (Fitting-net size: [240,240,240]) + +Embedding-net size | Energy L2err/Natoms(eV) | Force L2err(eV/Angstrom) +---|---|--- +[25,50,100] | 3.9606e-03 | 1.6289e-02 +[20,40,80] | 4.0292e-03 | 1.6555e-02 +[15,30,60] | 4.1743e-03 | 1.7026e-02 +[10,20,40] | 4.8138e-03 | 1.8516e-02 +[5,10,20] | 5.6052e-03 | 2.0709e-02 +[4,8,16] | 6.1335e-03 | 2.1450e-02 +[3,6,12] | 6.6469e-03 | 2.3003e-02 +[2,4,8] | 6.8222e-03 | 2.6318e-02 +[1,2,4] | 1.0678e-02 | 3.9559e-02 diff --git a/doc/troubleshooting/howtoset_num_nodes.md b/doc/troubleshooting/howtoset_num_nodes.md new file mode 100644 index 0000000000..c9b10c5197 --- /dev/null +++ b/doc/troubleshooting/howtoset_num_nodes.md @@ -0,0 +1,16 @@ +# How to control the number of nodes used by a job ? + +Set the number of CPU nodes used by DP algorithms with: +```bash +mpirun -np $num_nodes dp +``` +Set the number of threads used by DP algorithms with: +```bash +export OMP_NUM_THREADS = $num_threads +``` + +Set the number of CPU nodes used by TF kernels with: +```bash +export TF_INTRA_OP_PARALLELISM_THREADS = $num_nodes +export TF_INTER_OP_PARALLELISM_THREADS = $num_nodes +``` diff --git a/doc/troubleshooting/howtoset_rcut.md b/doc/troubleshooting/howtoset_rcut.md new file mode 100644 index 0000000000..f8ba56ccaa --- /dev/null +++ b/doc/troubleshooting/howtoset_rcut.md @@ -0,0 +1,7 @@ +# Do we need to set rcut < half boxsize ? + +When seeking the neighbors of atom i under periodic boundary condition, deepmd-kit considers all j atoms within cutoff rcut from atom i in all mirror cells. + +So, so there is no limitation on the setting of rcut. + +PS: The reason why some softwares require rcut < half boxsize is that they only consider the nearest mirrors from the center cell. Deepmd-kit is totally different from them. diff --git a/doc/troubleshooting/howtoset_sel.md b/doc/troubleshooting/howtoset_sel.md new file mode 100644 index 0000000000..0934a3b203 --- /dev/null +++ b/doc/troubleshooting/howtoset_sel.md @@ -0,0 +1,15 @@ +# How to set sel ? + +The setting of "sel" is related to "rcut" and the coordination number of certain atoms. Some empirical settings on some specific systems are listed below. + + +system | rcut | sel +---|---|--- +Li | 9.0 | [700] +Li | 6.0 | [200] +Si | 6.0 | [300] +water | 6.0 | [200,400] + +There is no optimal setting for rcut or sel. They depend on your system and the problem you aim to solve. + +Generally, you may need a larger rcut for metallic systems. As for semiconductor systems, choose a rcut with the third-nearest neighbors included is usually good enough. And as for molecular systems, they are more complex and circumstance specific. diff --git a/doc/troubleshooting/index.md b/doc/troubleshooting/index.md index 0db7b82198..1c7d642355 100644 --- a/doc/troubleshooting/index.md +++ b/doc/troubleshooting/index.md @@ -1,10 +1,16 @@ -# Troubleshooting +# FAQs In consequence of various differences of computers or systems, problems may occur. Some common circumstances are listed as follows. +In addition, some frequently asked questions about parameters setting are listed as follows. If other unexpected problems occur, you're welcome to contact us for help. - +## Trouble shooting - [Installation](installation.md) - [The temperature undulates violently during early stages of MD](md-energy-undulation.md) - [MD: cannot run LAMMPS after installing a new version of DeePMD-kit](md-version-compatibility.md) - [Model compatability](model-compatability.md) -- [Do we need to set rcut < half boxsize ?](rcut.md) + +## Parameters setting +- [How to tune Fitting/embedding-net size ?](howtoset_netsize.md) +- [How to control the number of nodes used by a job ?](howtoset_num_nodes.md) +- [Do we need to set rcut < half boxsize ?](howtoset_rcut.md) +- [How to set sel ?](howtoset_sel.md) diff --git a/doc/troubleshooting/rcut.md b/doc/troubleshooting/rcut.md deleted file mode 100644 index 147df0782b..0000000000 --- a/doc/troubleshooting/rcut.md +++ /dev/null @@ -1,7 +0,0 @@ -# Do we need to set rcut < half boxsize ? - -When seeking the neighbors of atom i under periodic boundary condition, deepmd-kit considers all j atoms within cutoff Rcut from atom i in all mirror cells. - -So, no, so there is no limitation on the setting of Rcut. - -PS: The reason why some softwares require Rcut < half boxsize is that they only consider the nearest mirrors from the center cell. Deepmd-kit is totally different from them. From 8fd2786ab868e8836834ae9031b938dcfaed6de2 Mon Sep 17 00:00:00 2001 From: tuoping Date: Fri, 21 May 2021 18:16:52 +0800 Subject: [PATCH 57/66] merge --- doc/conf.py | 23 ----------------------- doc/troubleshooting/index.md | 9 --------- doc/troubleshooting/rcut.md | 7 ------- 3 files changed, 39 deletions(-) delete mode 100644 doc/troubleshooting/rcut.md diff --git a/doc/conf.py b/doc/conf.py index 7fe9d1a2dd..71488ac4e0 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -20,7 +20,6 @@ def mkindex(dirname): oldfindex = open(dirname + "index.md", "r") oldlist = oldfindex.readlines() oldfindex.close() -<<<<<<< HEAD oldnames = [] for entry in oldlist: @@ -80,20 +79,6 @@ def classify_index_TS(): f = open(dirname + name, "r") _lines = f.readlines() f.close() -======= - - oldnames = [] - for entry in oldlist: - _name = entry[entry.find("(")+1 : entry.find(")")] - oldnames.append(_name) - - newfindex = open(dirname + "index.md", "a") - for root, dirs, files in os.walk(dirname, topdown=False): - newnames = [name for name in files if name != "index.md" and name not in oldnames] - for name in newnames: - f = open(dirname + name, "r") - _lines = f.readlines() ->>>>>>> 363f9ba435f3394f883c1e0a484005b86cb56c45 for _headline in _lines: _headline = _headline.strip("#") headline = _headline.strip() @@ -102,15 +87,10 @@ def classify_index_TS(): else: break longname = "- ["+headline+"]"+"("+name+")\n" -<<<<<<< HEAD if ("howtoset_" in name): sub_lists[1].append(longname) else: sub_lists[0].append(longname) -======= - newfindex.write(longname) - ->>>>>>> 363f9ba435f3394f883c1e0a484005b86cb56c45 newfindex.write("## Trouble shooting\n") for entry in sub_lists[0]: @@ -144,10 +124,7 @@ def classify_index_TS(): mkindex("troubleshooting") mkindex("development") -<<<<<<< HEAD classify_index_TS() -======= ->>>>>>> 363f9ba435f3394f883c1e0a484005b86cb56c45 extensions = [ "sphinx_rtd_theme", diff --git a/doc/troubleshooting/index.md b/doc/troubleshooting/index.md index 1d08be9925..1c7d642355 100644 --- a/doc/troubleshooting/index.md +++ b/doc/troubleshooting/index.md @@ -2,24 +2,15 @@ In consequence of various differences of computers or systems, problems may occur. Some common circumstances are listed as follows. In addition, some frequently asked questions about parameters setting are listed as follows. If other unexpected problems occur, you're welcome to contact us for help. -<<<<<<< HEAD ## Trouble shooting -======= - - ->>>>>>> 363f9ba435f3394f883c1e0a484005b86cb56c45 - [Installation](installation.md) - [The temperature undulates violently during early stages of MD](md-energy-undulation.md) - [MD: cannot run LAMMPS after installing a new version of DeePMD-kit](md-version-compatibility.md) - [Model compatability](model-compatability.md) -<<<<<<< HEAD ## Parameters setting - [How to tune Fitting/embedding-net size ?](howtoset_netsize.md) - [How to control the number of nodes used by a job ?](howtoset_num_nodes.md) - [Do we need to set rcut < half boxsize ?](howtoset_rcut.md) - [How to set sel ?](howtoset_sel.md) -======= -- [Do we need to set rcut < half boxsize ?](rcut.md) ->>>>>>> 363f9ba435f3394f883c1e0a484005b86cb56c45 diff --git a/doc/troubleshooting/rcut.md b/doc/troubleshooting/rcut.md deleted file mode 100644 index 74aafe72e1..0000000000 --- a/doc/troubleshooting/rcut.md +++ /dev/null @@ -1,7 +0,0 @@ -# Do we need to set rcut < half boxsize ? - -When seeking the neighbors of atom i under periodic boundary condition, deepmd-kit considers all j atoms within cutoff Rcut from atom i in all mirror cells. - -So there is no limitation on the setting of Rcut. - -PS: The reason why some softwares require Rcut < half boxsize is that they only consider the nearest mirrors from the center cell. Deepmd-kit is totally different from them. From b20324a212bdb7705008ce4ceddde5a8be897874 Mon Sep 17 00:00:00 2001 From: tuoping <80671886+tuoping@users.noreply.github.com> Date: Sun, 23 May 2021 18:54:38 +0800 Subject: [PATCH 58/66] Update doc/troubleshooting/howtoset_num_nodes.md Co-authored-by: Jinzhe Zeng --- doc/troubleshooting/howtoset_num_nodes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/troubleshooting/howtoset_num_nodes.md b/doc/troubleshooting/howtoset_num_nodes.md index c9b10c5197..db67b87f44 100644 --- a/doc/troubleshooting/howtoset_num_nodes.md +++ b/doc/troubleshooting/howtoset_num_nodes.md @@ -6,7 +6,7 @@ mpirun -np $num_nodes dp ``` Set the number of threads used by DP algorithms with: ```bash -export OMP_NUM_THREADS = $num_threads +export OMP_NUM_THREADS=$num_threads ``` Set the number of CPU nodes used by TF kernels with: From ac00229b150a6e35d2743b71e9923553896c3b97 Mon Sep 17 00:00:00 2001 From: tuoping <80671886+tuoping@users.noreply.github.com> Date: Sun, 23 May 2021 18:57:56 +0800 Subject: [PATCH 59/66] Update doc/troubleshooting/howtoset_num_nodes.md Co-authored-by: Jinzhe Zeng --- doc/troubleshooting/howtoset_num_nodes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/troubleshooting/howtoset_num_nodes.md b/doc/troubleshooting/howtoset_num_nodes.md index db67b87f44..131732ea42 100644 --- a/doc/troubleshooting/howtoset_num_nodes.md +++ b/doc/troubleshooting/howtoset_num_nodes.md @@ -11,6 +11,6 @@ export OMP_NUM_THREADS=$num_threads Set the number of CPU nodes used by TF kernels with: ```bash -export TF_INTRA_OP_PARALLELISM_THREADS = $num_nodes -export TF_INTER_OP_PARALLELISM_THREADS = $num_nodes +export TF_INTRA_OP_PARALLELISM_THREADS=$num_nodes +export TF_INTER_OP_PARALLELISM_THREADS=$num_nodes ``` From f8e0421e2bcb1c42ca7cc48c796351114ce4148b Mon Sep 17 00:00:00 2001 From: tuoping Date: Mon, 24 May 2021 18:56:59 +0800 Subject: [PATCH 60/66] add explanation for [] in troubleshooting/howtoset_netsize.md --- doc/troubleshooting/howtoset_netsize.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/troubleshooting/howtoset_netsize.md b/doc/troubleshooting/howtoset_netsize.md index 93c981e2e4..800abb9a08 100644 --- a/doc/troubleshooting/howtoset_netsize.md +++ b/doc/troubleshooting/howtoset_netsize.md @@ -21,6 +21,8 @@ Fitting-net size | Energy L2err(eV) | Energy L2err/Natoms(eV) | Force L2err(eV/A [1,1,1] | 2.813596e-02 | 1.172332e-04 | 4.781115e-02 [] | 3.135002e-02 | 1.306251e-04 | 5.373120e-02 +_[] means no hidden layer, but there is still a linear output layer. This situation is equal to the linear regression._ + ### Embedding net size tuning form on Al2O3: (Fitting-net size: [240,240,240]) Embedding-net size | Energy L2err(eV) | Energy L2err/Natoms(eV) | Force L2err(eV/Angstrom) From c024c15d1c0d09d5dc42b52f990c42bf6add83d8 Mon Sep 17 00:00:00 2001 From: tuoping <80671886+tuoping@users.noreply.github.com> Date: Tue, 25 May 2021 08:21:05 +0800 Subject: [PATCH 61/66] Update howtoset_sel.md --- doc/troubleshooting/howtoset_sel.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/doc/troubleshooting/howtoset_sel.md b/doc/troubleshooting/howtoset_sel.md index 0934a3b203..22436da3e0 100644 --- a/doc/troubleshooting/howtoset_sel.md +++ b/doc/troubleshooting/howtoset_sel.md @@ -9,7 +9,3 @@ Li | 9.0 | [700] Li | 6.0 | [200] Si | 6.0 | [300] water | 6.0 | [200,400] - -There is no optimal setting for rcut or sel. They depend on your system and the problem you aim to solve. - -Generally, you may need a larger rcut for metallic systems. As for semiconductor systems, choose a rcut with the third-nearest neighbors included is usually good enough. And as for molecular systems, they are more complex and circumstance specific. From 03a79a5083b82ab82df82de277e8f918b6ebe6b1 Mon Sep 17 00:00:00 2001 From: tuoping <80671886+tuoping@users.noreply.github.com> Date: Tue, 25 May 2021 08:47:59 +0800 Subject: [PATCH 62/66] Update howtoset_sel.md Add the definition of sel and the principle of setting sel. --- doc/troubleshooting/howtoset_sel.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/troubleshooting/howtoset_sel.md b/doc/troubleshooting/howtoset_sel.md index 22436da3e0..90a957f777 100644 --- a/doc/troubleshooting/howtoset_sel.md +++ b/doc/troubleshooting/howtoset_sel.md @@ -1,8 +1,9 @@ # How to set sel ? +sel_a[i] is a list of integers. The length of the list should be the same as the number of atom types in the system. +sel_a[i] gives the selected number of type-i neighbors. The full relative coordinates of the neighbors are used by the descriptor. The setting of "sel" is related to "rcut" and the coordination number of certain atoms. Some empirical settings on some specific systems are listed below. - system | rcut | sel ---|---|--- Li | 9.0 | [700] From 8c7a89b8c4c5e326a6c427a6078136a2273da3e0 Mon Sep 17 00:00:00 2001 From: tuoping <80671886+tuoping@users.noreply.github.com> Date: Tue, 25 May 2021 08:48:37 +0800 Subject: [PATCH 63/66] Update howtoset_sel.md --- doc/troubleshooting/howtoset_sel.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/troubleshooting/howtoset_sel.md b/doc/troubleshooting/howtoset_sel.md index 90a957f777..97eee47229 100644 --- a/doc/troubleshooting/howtoset_sel.md +++ b/doc/troubleshooting/howtoset_sel.md @@ -1,7 +1,9 @@ # How to set sel ? sel_a[i] is a list of integers. The length of the list should be the same as the number of atom types in the system. + sel_a[i] gives the selected number of type-i neighbors. The full relative coordinates of the neighbors are used by the descriptor. + The setting of "sel" is related to "rcut" and the coordination number of certain atoms. Some empirical settings on some specific systems are listed below. system | rcut | sel From e3103d82ea5cf25aa4ce8e354785a387ec446719 Mon Sep 17 00:00:00 2001 From: tuoping Date: Tue, 25 May 2021 13:36:04 +0800 Subject: [PATCH 64/66] Edited howtoset_sel.md --- doc/troubleshooting/howtoset_sel.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/doc/troubleshooting/howtoset_sel.md b/doc/troubleshooting/howtoset_sel.md index 97eee47229..7d552e7bd4 100644 --- a/doc/troubleshooting/howtoset_sel.md +++ b/doc/troubleshooting/howtoset_sel.md @@ -1,10 +1,16 @@ # How to set sel ? -sel_a[i] is a list of integers. The length of the list should be the same as the number of atom types in the system. +`sel` is short for "selected number of atoms in `rcut`". -sel_a[i] gives the selected number of type-i neighbors. The full relative coordinates of the neighbors are used by the descriptor. +`sel_a[i]` is a list of integers. The length of the list should be the same as the number of atom types in the system. -The setting of "sel" is related to "rcut" and the coordination number of certain atoms. Some empirical settings on some specific systems are listed below. +`sel_a[i]` gives the number neighbors of type-i within `rcut`. To ensure that the results are strictly accurate, `sel_a[i]` should be larger than the largest number of neighbors of type-i. + +However, the computation overhead increases with `sel_a[i]`, therefore, `sel_a[i]` should be as small as possible. + +The setting of `sel_a[i]` should balance the above two considerations. + +Here are some empirical settings: system | rcut | sel ---|---|--- From e72c624b505f4a9fcb1d7c1b07bac837ee2d5409 Mon Sep 17 00:00:00 2001 From: tuoping <80671886+tuoping@users.noreply.github.com> Date: Wed, 26 May 2021 15:22:40 +0800 Subject: [PATCH 65/66] Update howtoset_sel.md Deleted the empirical examples. --- doc/troubleshooting/howtoset_sel.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/doc/troubleshooting/howtoset_sel.md b/doc/troubleshooting/howtoset_sel.md index 7d552e7bd4..81d9b29bd3 100644 --- a/doc/troubleshooting/howtoset_sel.md +++ b/doc/troubleshooting/howtoset_sel.md @@ -9,12 +9,3 @@ However, the computation overhead increases with `sel_a[i]`, therefore, `sel_a[i]` should be as small as possible. The setting of `sel_a[i]` should balance the above two considerations. - -Here are some empirical settings: - -system | rcut | sel ----|---|--- -Li | 9.0 | [700] -Li | 6.0 | [200] -Si | 6.0 | [300] -water | 6.0 | [200,400] From 4b58dd9e318751f61da4d19cc45d9c09f27fc0e6 Mon Sep 17 00:00:00 2001 From: Han Wang Date: Sat, 29 May 2021 20:03:35 +0800 Subject: [PATCH 66/66] Update howtoset_sel.md --- doc/troubleshooting/howtoset_sel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/troubleshooting/howtoset_sel.md b/doc/troubleshooting/howtoset_sel.md index 81d9b29bd3..915fdd3094 100644 --- a/doc/troubleshooting/howtoset_sel.md +++ b/doc/troubleshooting/howtoset_sel.md @@ -4,7 +4,7 @@ `sel_a[i]` is a list of integers. The length of the list should be the same as the number of atom types in the system. -`sel_a[i]` gives the number neighbors of type-i within `rcut`. To ensure that the results are strictly accurate, `sel_a[i]` should be larger than the largest number of neighbors of type-i. +`sel_a[i]` gives the number of selected number of type `i` neighbors within `rcut`. To ensure that the results are strictly accurate, `sel_a[i]` should be larger than the largest number of type `i` neighbors in the `rcut`. However, the computation overhead increases with `sel_a[i]`, therefore, `sel_a[i]` should be as small as possible.