Documentation improvements

README.md

@@ -124,35 +124,28 @@ A full [document](doc/train/train-input-auto.rst) on options in the training inp
     - [Run MD with GROMACS](doc/third-party/gromacs.md)
 
 # Code structure
+
 The code is organized as follows:
 
 * `data/raw`: tools manipulating the raw data files.
-
 * `examples`: examples.
-
 * `deepmd`: DeePMD-kit python modules.
-
 * `source/api_cc`: source code of DeePMD-kit C++ API.
-
 * `source/ipi`: source code of i-PI client.
-
 * `source/lib`: source code of DeePMD-kit library.
-
 * `source/lmp`: source code of Lammps module.
-
 * `source/gmx`: source code of Gromacs plugin.
-
 * `source/op`: tensorflow op implementation. working with library.
 
 
 # Troubleshooting
 
-- [Model compatibility](doc/troubleshooting/model-compatability.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)
+- [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)
 

doc/model/overall.md

@@ -1,6 +1,6 @@
 # Overall
 
-A model has two parts, a descriptor that maps atomic configuration to a set of symmetry invariant features, and a fitting net that takes descriptor as input and predicts the atomic contribution to the target physical property. It's defined in the `model` section of the `input.json`, for example
+A model has two parts, a descriptor that maps atomic configuration to a set of symmetry invariant features, and a fitting net that takes descriptor as input and predicts the atomic contribution to the target physical property. It's defined in the `model` section of the `input.json`, for example,
 ```json
     "model": {
         "type_map":	["O", "H"],
@@ -12,10 +12,9 @@ A model has two parts, a descriptor that maps atomic configuration to a set of s
         }
     }
 ```
+The two subsections, `descriptor` and `fitting_net`, define the descriptor and the fitting net, respectively.
 
-Assume that we are looking for a model for water, we will have two types of atoms. The atom types are recorded as integers. In this example, we denote `0` for oxygen and `1` for hydrogen. A mapping from the atom type to their names is provided by `type_map`. 
-
-The model has two subsections `descritpor` and `fitting_net`, which defines the descriptor and the fitting net, respectively. The `type_map` is optional, which provides the element names (but not necessarily to be the element name) of the corresponding atom types.
+The `type_map` is optional, which provides the element names (but not necessarily same with the actual name of the element) of the corresponding atom types. A model for water, as in this example, has two kinds of atoms. The atom types are internally recorded as integers, e.g., `0` for oxygen and `1` for hydrogen here. A mapping from the atom type to their names is provided by `type_map`. 
 
 DeePMD-kit implements the following descriptors:
 1. [`se_e2_a`](train-se-e2-a.md): DeepPot-SE constructed from all information (both angular and radial) of atomic configurations. The embedding takes the distance between atoms as input.
@@ -25,6 +24,6 @@ DeePMD-kit implements the following descriptors:
 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-energy.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#loss).
+1. [`ener`](train-energy.md): Fit the energy of the system. The force (derivative with atom positions) and the virial (derivative with the box tensor) can also be trained. See [the example](train-se-e2-a.md#loss).
 2. [`dipole`](train-fitting-tensor.md): The dipole moment.
 3. [`polar`](train-fitting-tensor.md): The polarizability.

doc/model/train-energy.md

@@ -2,7 +2,7 @@
 
 In this section, we will take `$deepmd_source_dir/examples/water/se_e2_a/input.json` as an example of the input file.
 
-## Fitting network
+## The fitting network
 
 The construction of the fitting net is give by section `fitting_net`
 ```json

doc/model/train-fitting-tensor.md

@@ -1,6 +1,6 @@
 # Fit `tensor` like `Dipole` and `Polarizability`
 
-Unlike `energy` which is a scalar, one may want to fit some high dimensional physical quantity, like `dipole` (vector) and `polarizability` (matrix, shorted as `polar`). Deep Potential has provided different API to allow this. In this example we will show you how to train a model to fit them for a water system. A complete training input script of the examples can be found in 
+Unlike `energy`, which is a scalar, one may want to fit some high dimensional physical quantity, like `dipole` (vector) and `polarizability` (matrix, shorted as `polar`). Deep Potential has provided different APIs to do this. In this example, we will show you how to train a model to fit them for a water system. A complete training input script of the examples can be found in 
 
 ```bash
 $deepmd_source_dir/examples/water_tensor/dipole/dipole_input.json
@@ -11,7 +11,7 @@ The training and validation data are also provided our examples. But note that *
 
 Similar to the `input.json` used in `ener` mode, training json is also divided into `model`, `learning_rate`, `loss` and `training`. Most keywords remains the same as `ener` mode, and their meaning can be found [here](train-se-e2-a.md). To fit a tensor, one need to modify `model.fitting_net` and `loss`.
 
-## Fitting Network
+## The fitting Network
 
 The `fitting_net` section tells DP which fitting net to use.
 

doc/train/training.md

@@ -1,4 +1,4 @@
-# Training a model
+# Train a model
 
 Several examples of training can be found at the `examples` directory:
 ```bash