From 068d2fb68cc042d4c40b98a95740bfec30a1744e Mon Sep 17 00:00:00 2001 From: Han Wang Date: Tue, 20 Apr 2021 15:22:43 +0800 Subject: [PATCH] add what's new in v2.0 to readme. move troubleshooting to a separate page --- README.md | 79 +++++++++++++++--------------------------- doc/troubleshooting.md | 37 ++++++++++++++++++++ 2 files changed, 65 insertions(+), 51 deletions(-) create mode 100644 doc/troubleshooting.md diff --git a/README.md b/README.md index e32df9eb70..a70644f9b3 100644 --- a/README.md +++ b/README.md @@ -5,12 +5,13 @@ # Table of contents - [About DeePMD-kit](#about-deepmd-kit) + - [Highlights in v2.0](#highlights-in-deepmd-kit-v2.0) - [Highlighted features](#highlighted-features) - - [Code structure](#code-structure) - [License and credits](#license-and-credits) - [Deep Potential in a nutshell](#deep-potential-in-a-nutshell) - [Download and install](#download-and-install) - [Use DeePMD-kit](#use-deepmd-kit) +- [Code structure](#code-structure) - [Troubleshooting](#troubleshooting) # About DeePMD-kit @@ -18,6 +19,17 @@ 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. * **interfaced with high-performance classical MD and quantum (path-integral) MD packages**, i.e., LAMMPS and i-PI, respectively. @@ -25,28 +37,6 @@ For more information, check the [documentation](https://deepmd.readthedocs.io/). * **implements MPI and GPU supports**, makes it highly efficient for high performance parallel and distributed computing. * **highly modularized**, easy to adapt to different descriptors for deep learning based potential energy models. -## Code structure -The code is organized as follows: - -* `data/raw`: tools manipulating the raw data files. - -* `examples`: example json parameter files. - -* `source/3rdparty`: third-party packages used by DeePMD-kit. - -* `source/cmake`: cmake scripts for building. - -* `source/ipi`: source code of i-PI client. - -* `source/lib`: source code of DeePMD-kit library. - -* `source/lmp`: source code of Lammps module. - -* `source/op`: tensorflow op implementation. working with library. - -* `source/train`: Python modules and scripts for training and testing. - - ## License and credits The project DeePMD-kit is licensed under [GNU LGPLv3.0](./LICENSE). If you use this code in any future publications, please cite this using @@ -87,43 +77,30 @@ 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. -# 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. +# Code structure +The code is organized as follows: -## Model compatability +* `data/raw`: tools manipulating the raw data files. -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. +* `examples`: examples. -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. +* `deepmd`: DeePMD-kit python modules. -## 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++ -``` +* `source/api_cc`: source code of DeePMD-kit C++ API. -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. +* `source/ipi`: source code of i-PI client. -## 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. +* `source/lib`: source code of DeePMD-kit library. + +* `source/lmp`: source code of Lammps module. -## 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. +* `source/op`: tensorflow op implementation. working with library. -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. + +# Troubleshooting + +See the [troubleshooting page](doc/troubleshooting.md). [1]: http://www.global-sci.com/galley/CiCP-2017-0213.pdf diff --git a/doc/troubleshooting.md b/doc/troubleshooting.md new file mode 100644 index 0000000000..afdcdf9985 --- /dev/null +++ b/doc/troubleshooting.md @@ -0,0 +1,37 @@ +# 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.