Merge pull request #18 from deepmodeling/devel

Devel update

.github/ISSUE_TEMPLATE/bug-report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: Create a bug report to help us eliminate issues and improve deepmd-kit. If
+  this doesn’t look right, [choose a different type](https://github.com/deepmodeling/deepmd-kit/issues/new/choose).
+title: "[BUG] _Replace With Suitable Title_"
+labels: bug
+assignees: ''
+
+---
+
+**Summary**
+
+<!--Please provide a clear and concise description of what the bug is.-->
+
+**Deepmd-kit version, installation way, input file, running commands, error log, etc.**
+
+<!--Please provide necessary information including the version of software and installation way, input file, running commands, error log , etc., AS  DETAILED AS POSSIBLE to help locate and reproduce your problem. !!! WARNING: Do not use image to show error log! Paste texts in a code block instead. !!!-->
+
+<!--If applicable, specify what platform you are running on. -->
+
+**Steps to Reproduce**
+
+<!--Describe the steps required to (quickly) reproduce the issue. You can attach (small) files to the section below or add URLs where to download an archive with all necessary files. Please try to create an input set that is as minimal and small as possible and reproduces the bug as quickly as possible. **NOTE:** the less effort and time it takes to reproduce your reported bug, the more likely it becomes, that somebody will look into it and fix the problem.-->
+
+**Further Information, Files, and Links**
+
+<!--Put any additional information here, attach relevant text or image files and URLs to external sites, e.g. relevant publications-->

.github/ISSUE_TEMPLATE/feature-request.md

@@ -0,0 +1,21 @@
+---
+name: Feature request
+about: Suggest an idea for this project. If this doesn’t work right, [choose a different
+  type]( https://github.com/deepmodeling/deepmd-kit/issues/new/choose)
+title: "[Feature Request] _Replace with Title_"
+labels: enhancement
+assignees: ''
+
+---
+
+**Summary**
+
+<!--Please provide a brief and concise description of the suggested feature or change-->
+
+**Detailed Description**
+
+<!--Please explain how you would like to see deepmd-kit enhanced, what feature(s) you are looking for, what specific problems this will solve. If possible, provide references to relevant background information like publications or web pages, and whether you are planning to implement the enhancement yourself or would like to participate in the implementation. If applicable add a reference to an existing bug report or issue that this will address.-->
+
+**Further Information, Files, and Links**
+
+<!--Put any additional information here, attach relevant text or image files and URLs to external sites, e.g. relevant publications-->

.github/ISSUE_TEMPLATE/generic-issue.md

@@ -0,0 +1,23 @@
+---
+name: Generic issue
+about: For issues that do not fit any of the other categories. If this doesn’t work
+  right, [choose a different type]( https://github.com/deepmodeling/deepmd-kit/issues/new/choose).
+title: _Replace With a Descriptive Title_
+labels: wontfix
+assignees: ''
+
+---
+
+**Summary**
+
+<!--Please provide a clear and concise description of what the question is.-->
+
+**Deepmd-kit Version, Python Version, Tensorflow Version, GCC Version and Cuda Version.**
+
+<!--Please specify precisely which Deepmd-kit version this issue was detected with on what build environment, (Python Version and GCC Version are in the first and second line of Python command line interface respectively. And check the Deepmd-kit Version with command line "print(deepmd.__version__)"). -->
+
+<!--If applicable, specify what platform you are running on. -->
+
+**Details**
+
+<!--Please explain the issue in detail here-->

.github/ISSUE_TEMPLATE/parameters.md

@@ -0,0 +1,25 @@
+---
+name: Parameters
+about: Make a suggestion for a change of input parameters or a new output to deepmd-kit.
+  If this doesn’t work right, [choose a different type]( https://github.com/deepmodeling/deepmd-kit/issues/new/choose).
+title: "[Parameters] _Replace With Suitable Title_"
+labels: documentation, enhancement
+assignees: ''
+
+---
+
+**Summary**
+
+<!--Please provide a clear and concise description of what your request is.-->
+
+**Summary**
+
+<!--Please provide a brief and concise description of the suggested feature or change-->
+
+**Detailed Description**
+
+<!--Please explain how you would like to see deepmd-kit enhanced. Specify your material system, and exactly what behaviors or properties you are looking for, or what specific problems this will solve. If possible, provide references to relevant background information like publications or web pages, and whether you are planning to implement the enhancement yourself or would like to participate in the implementation.-->
+
+**Further Information, Files, and Links**
+
+<!--Put any additional information here, attach relevant text or image files and URLs to external sites, e.g. relevant publications-->

.github/ISSUE_TEMPLATE/request-for-help.md

@@ -0,0 +1,21 @@
+---
+name: Request for Help
+about: Don't post help requests here, go to [discussions](https://github.com/deepmodeling/deepmd-kit/discussions)
+  instead.
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+Before asking questions, you can
+
+search the previous issues or discussions
+check the [document](https://deepmd.readthedocs.io/en/stable), especially [training parameters](https://deepmd.readthedocs.io/en/stable/train-input.html).
+
+Please **do not** post requests for help (e.g. with installing or using deepmd-kit) here. 
+Instead go to [discussions](https://github.com/deepmodeling/deepmd-kit/discussions).
+
+This issue tracker is for tracking deepmd-kit development related issues only.
+
+Thanks for your cooperation.

.github/workflows/build_cc.yml

@@ -9,14 +9,8 @@ jobs:
     strategy:  
       matrix:
         include:
-        - float_prec: high
-          variant: cpu
-        - float_prec: low
-          variant: cpu
-        - float_prec: high
-          variant: cuda
-        - float_prec: low
-          variant: cuda
+        - variant: cpu
+        - variant: cuda
     steps:
     - uses: actions/checkout@master
       with:
@@ -26,12 +20,6 @@ jobs:
       if: matrix.variant == 'cuda'
     - run: source/install/build_cc.sh
       env:
-        FLOAT_PREC: ${{ matrix.float_prec }}
         DP_VARIANT: ${{ matrix.variant }}
         CC: gcc-7
         CXX: g++-7
-    - run: source/install/build_lammps.sh
-      env:
-        FLOAT_PREC: ${{ matrix.float_prec }}
-        CC: gcc-7
-        CXX: g++-7

.github/workflows/test_python.yml

@@ -38,16 +38,16 @@ jobs:
             tf: 1.14
           - python: 3.7
             gcc: 5
-            tf: 2.3
+            tf:
           - python: 3.7
             gcc: 8
-            tf: 2.3
+            tf:
           - python: 3.8
             gcc: 5
-            tf: 2.3
+            tf:
           - python: 3.8
             gcc: 8
-            tf: 2.3
+            tf:
 
     steps:
     - uses: actions/checkout@master
@@ -70,4 +70,5 @@ jobs:
         CC: gcc-${{ matrix.gcc }}
         CXX: g++-${{ matrix.gcc }}
         TENSORFLOW_VERSION: ${{ matrix.tf }}
+    - run: dp --version
     - run: pytest --cov=deepmd source/tests && codecov

.gitignore

@@ -27,7 +27,8 @@ venv*
 _build
 _templates
 API_CC
+doc/api_py/
 dp/
 build_lammps/
 build_tests/
-build_cc_tests
+build_cc_tests

CITATION.cff

@@ -0,0 +1,19 @@
+preferred-citation:
+  type: article
+  authors:
+  - family-names: "Wang"
+    given-names: "Han"
+  - family-names: "Zhang"
+    given-names: "Linfeng"
+  - family-names: "Han"
+    given-names: "Jiequn"
+  - family-names: "E"
+    given-names: "Weinan"
+  doi: "10.1016/j.cpc.2018.03.016"
+  journal: "Computer Physics Communications"
+  month: 7
+  start: 178 # First page number
+  end: 184 # Last page number
+  title: "DeePMD-kit: A deep learning package for many-body potential energy representation and molecular dynamics"
+  volume: 228
+  year: 2018

README.md

@@ -1,7 +1,11 @@
 <span style="font-size:larger;">DeePMD-kit Manual</span>
 ========
 [![GitHub release](https://img.shields.io/github/release/deepmodeling/deepmd-kit.svg?maxAge=86400)](https://github.com/deepmodeling/deepmd-kit/releases)
-[![Documentation Status](https://readthedocs.org/projects/deepmd/badge/?version=latest)](https://deepmd.readthedocs.io/en/latest/?badge=latest)
+[![doi:10.1016/j.cpc.2018.03.016](https://img.shields.io/badge/DOI-10.1016%2Fj.cpc.2018.03.016-blue)](https://doi.org/10.1016/j.cpc.2020.107206)
+[![offline packages](https://img.shields.io/github/downloads/deepmodeling/deepmd-kit/total?label=offline%20packages)](https://github.com/deepmodeling/deepmd-kit/releases)
+[![pip install](https://img.shields.io/pypi/dm/deepmd-kit?label=pip%20install)](https://pypi.org/project/deepmd-kit)
+[![docker pull](https://img.shields.io/docker/pulls/deepmodeling/deepmd-kit)](https://hub.docker.com/r/deepmodeling/deepmd-kit)
+[![Documentation Status](https://readthedocs.org/projects/deepmd/badge/)](https://deepmd.readthedocs.io/)
 
 # Table of contents
 - [About DeePMD-kit](#about-deepmd-kit)
@@ -20,10 +24,10 @@ 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/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](doc/train-se-e2-a-tebd.md). Enable atom type embedding to decline training complexity and refine performance.
+* [Model compression](doc/freeze/compress.md). Accelerate the efficiency of model inference for 4-15 times.
+* [New descriptors](doc/model/overall.md). Including [`se_e2_r`](doc/model/train-se-e2-r.md) and [`se_e3`](doc/model/train-se-e3.md).
+* [Hybridization of descriptors](doc/model/train-hybrid.md). Hybrid descriptor constructed from concatenation of several descriptors.
+* [Atom type embedding](doc/model/train-se-e2-a-tebd.md). Enable atom type embedding to decline training complexity and refine performance.
 * Training and inference the dipole (vector) and polarizability (matrix).
 * Split of training and validation dataset.
 * Optimized training on GPUs. 
@@ -51,28 +55,66 @@ In addition to building up potential energy models, DeePMD-kit can also be used
 
 # Download and install
 
-Please follow our [github](https://github.com/deepmodeling/deepmd-kit) webpage to download the [latest released version](https://github.com/deepmodeling/deepmd-kit/tree/master) and [development version](https://github.com/deepmodeling/deepmd-kit/tree/devel).
+Please follow our [GitHub](https://github.com/deepmodeling/deepmd-kit) webpage to download the [latest released version](https://github.com/deepmodeling/deepmd-kit/tree/master) and [development version](https://github.com/deepmodeling/deepmd-kit/tree/devel).
 
-DeePMD-kit offers multiple installation methods. It is recommend using easily methods like [offline packages](doc/install.md#offline-packages), [conda](doc/install.md#with-conda) and [docker](doc/install.md#with-docker). 
+DeePMD-kit offers multiple installation methods. It is recommend using easily methods like [offline packages](doc/install/easy-install.md#offline-packages), [conda](doc/install/easy-install.md#with-conda) and [docker](doc/install/easy-install.md#with-docker). 
 
-One may manually install DeePMD-kit by following the instuctions on [installing the python interface](doc/install.md#install-the-python-interface) and [installing the C++ interface](doc/install.md#install-the-c-interface). The C++ interface is necessary when using DeePMD-kit with LAMMPS and i-PI.
+One may manually install DeePMD-kit by following the instuctions on [installing the Python interface](doc/install/install-from-source.md#install-the-python-interface) and [installing the C++ interface](doc/install/install-from-source.md#install-the-c-interface). The C++ interface is necessary when using DeePMD-kit with LAMMPS and i-PI.
 
 
 # Use DeePMD-kit
 
-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)
-3. [Analyze training with Tensorboard](doc/tensorboard.md)
-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/getting-started.md).
-
-A full [document](doc/train-input-auto.rst) on options in the training input script is available.
+A quick-start on using DeePMD-kit can be found as follows:
+
+- [Prepare data with dpdata](doc/data/dpdata.md)
+- [Training a model](doc/train/training.md)
+- [Freeze a model](doc/freeze/freeze.md)
+- [Test a model](doc/test/test.md)
+- [Running MD with LAMMPS](doc/third-party/lammps.md)
+
+A full [document](doc/train/train-input-auto.rst) on options in the training input script is available.
+
+# Advanced
+
+- [Installation](doc/install/index.md)
+    - [Easy install](doc/install/easy-install.md)
+    - [Install from source code](doc/install/install-from-source.md)
+    - [Install LAMMPS](doc/install/install-lammps.md)
+    - [Install i-PI](doc/install/install-ipi.md)
+    - [Building conda packages](doc/install/build-conda.md)
+- [Data](doc/data/index.md)
+    - [Data conversion](doc/data/data-conv.md)
+    - [Prepare data with dpdata](doc/data/dpdata.md)
+- [Model](doc/model/index.md)
+    - [Overall](doc/model/overall.md)
+    - [Descriptor `"se_e2_a"`](doc/model/train-se-e2-a.md)
+    - [Descriptor `"se_e2_r"`](doc/model/train-se-e2-r.md)
+    - [Descriptor `"se_e3"`](doc/model/train-se-e3.md)
+    - [Descriptor `"hybrid"`](doc/model/train-hybrid.md)
+    - [Fit energy](doc/model/train-energy.md)
+    - [Fit `tensor` like `Dipole` and `Polarizability`](doc/model/train-fitting-tensor.md)
+    - [Train a Deep Potential model using `type embedding` approach](doc/model/train-se-e2-a-tebd.md)
+- [Training](doc/train/index.md)
+    - [Training a model](doc/train/training.md)
+    - [Advanced options](doc/train/training-advanced.md)
+    - [Parallel training](doc/train/parallel-training.md)
+    - [TensorBoard Usage](doc/train/tensorboard.md)
+    - [Known limitations of using GPUs](doc/train/gpu-limitations.md)
+    - [Training Parameters](doc/train/train-input-auto.rst)
+- [Freeze and Compress](doc/freeze/index.rst)
+    - [Freeze a model](doc/freeze/freeze.md)
+    - [Compress a model](doc/freeze/compress.md)
+- [Test](doc/test/index.rst)
+    - [Test a model](doc/test/test.md)
+    - [Calculate Model Deviation](doc/test/model-deviation.md)
+- [Inference](doc/inference/index.rst)
+    - [Python interface](doc/inference/python.md)
+    - [C++ interface](doc/inference/cxx.md)
+- [Integrate with third-party packages](doc/third-party/index.rst)
+    - [Use deep potential with ASE](doc/third-party/ase.md)
+    - [Running MD with LAMMPS](doc/third-party/lammps.md)
+    - [LAMMPS commands](doc/third-party/lammps-command.md)
+    - [Run path-integral MD with i-PI](doc/third-party/ipi.md)
 
 
 # Code structure
@@ -97,7 +139,14 @@ The code is organized as follows:
 
 # Troubleshooting
 
-See the [troubleshooting page](doc/troubleshooting/index.md).
+- [Model compatibility](doc/troubleshooting/model-compatability.md)
+- [Installation](doc/troubleshooting/installation.md)
+- [The temperature undulates violently during early stages of MD](doc/troubleshooting/md-energy-undulation.md)
+- [MD: cannot run LAMMPS after installing a new version of DeePMD-kit](doc/troubleshooting/md-version-compatibility.md)
+- [Do we need to set rcut < half boxsize?](doc/troubleshooting/howtoset-rcut.md)
+- [How to set sel?](doc/troubleshooting/howtoset-sel.md)
+- [How to control the number of nodes used by a job?](doc/troubleshooting/howtoset_num_nodes.md)
+- [How to tune Fitting/embedding-net size?](doc/troubleshooting/howtoset_netsize.md)
 
 
 # Contributing

deepmd/calculator.py

@@ -1,10 +1,13 @@
 """ASE calculator interface module."""
 
-from typing import TYPE_CHECKING, Dict, List, Optional, Union
 from pathlib import Path
+from typing import TYPE_CHECKING, Dict, List, Optional, Union
+
+from ase.calculators.calculator import (
+    Calculator, all_changes, PropertyNotImplementedError
+)
 
 from deepmd import DeepPotential
-from ase.calculators.calculator import Calculator, all_changes
 
 if TYPE_CHECKING:
     from ase import Atoms
@@ -51,7 +54,7 @@ class DP(Calculator):
     """
 
     name = "DP"
-    implemented_properties = ["energy", "forces", "stress"]
+    implemented_properties = ["energy", "forces", "virial", "stress"]
 
     def __init__(
         self,
@@ -72,7 +75,7 @@ def __init__(
     def calculate(
         self,
         atoms: Optional["Atoms"] = None,
-        properties: List[str] = ["energy", "forces", "stress"],
+        properties: List[str] = ["energy", "forces", "virial"],
         system_changes: List[str] = all_changes,
     ):
         """Run calculation with deepmd model.
@@ -98,6 +101,17 @@ def calculate(
         symbols = self.atoms.get_chemical_symbols()
         atype = [self.type_dict[k] for k in symbols]
         e, f, v = self.dp.eval(coords=coord, cells=cell, atom_types=atype)
-        self.results["energy"] = e[0]
-        self.results["forces"] = f[0]
-        self.results["stress"] = v[0]
+        self.results['energy'] = e[0][0]
+        self.results['forces'] = f[0]
+        self.results['virial'] = v[0].reshape(3, 3)
+
+        # convert virial into stress for lattice relaxation
+        if "stress" in properties:
+            if sum(atoms.get_pbc()) > 0:
+                # the usual convention (tensile stress is positive)
+                # stress = -virial / volume
+                stress = -0.5 * (v[0].copy() + v[0].copy().T) / atoms.get_volume()
+                # Voigt notation
+                self.results['stress'] = stress.flat[[0, 4, 8, 5, 2, 1]]
+            else:
+                raise PropertyNotImplementedError