optimize autotest document based on #891

doc/autotest/Auto-test.md

@@ -0,0 +1,114 @@
+## Autotest Overview: Autotest for Deep Generator
+Suppose that we have a potential (can be DFT, DP, MEAM ...), `autotest` helps us automatically calculate M properties on N configurations. The folder where the `autotest` runs is called the working directory of `autotest`. Different potentials should be tested in different working directories.
+
+A property is tested in three steps: `make`, `run` and `post`. `make` prepares all computational tasks that are needed to calculate the property. For example to calculate EOS, `make` prepares a series of tasks, each of which has a scaled configuration with certain volume, and all necessary input files necessary for starting a VASP, ABACUS, or LAMMPS calculations. `run` sends all the computational tasks to remote computational resources defined in a machine configuration file like `machine.json`, and automatically collects the results when remote calculations finish. `post` calculates the desired property from the collected results.
+
+### Relaxation
+
+The relaxation of a structure should be carried out before calculating all other properties:
+```bash
+dpgen autotest make relax.json
+dpgen autotest run relax.json machine.json
+dpgen autotest post relax.json
+```
+If, for some reasons, the main program terminated at stage `run`, one can easily restart with the same command.
+`relax.json` is the parameter file. An example for `deepmd` relaxation is given as:
+```json
+{
+        "structures":   "confs/mp-*",
+        "interaction": {
+                "type":         "deepmd",
+                "model":        "frozen_model.pb",
+                "type_map":     {"Al": 0, "Mg": 1}
+        },
+        "relaxation": {}
+}
+```
+
+where the key `structures` provides the structures to relax. `interaction` is provided with `deepmd`, and other options are `vasp`, `abacus`, `meam`...
+
+### Task type
+There are now six task types implemented in the package: `vasp`, `abacus`, `deepmd`, `meam`, `eam_fs`, and `eam_alloy`. An `inter.json` file in json format containing the interaction parameters will be written in the directory of each task after `make`. We give input examples of the `interaction` part for each type below:
+
+**VASP**: 
+
+The default of `potcar_prefix` is "".
+```json
+	"interaction": {
+		"type":		"vasp",
+		"incar":	"vasp_input/INCAR",
+		"potcar_prefix":"vasp_input",
+		"potcars":	{"Al": "POTCAR.al", "Mg": "POTCAR.mg"}
+	}
+```
+**ABACUS**: 
+
+The default of `potcar_prefix` is "". The path of potcars/orb_files/deepks_desc is `potcar_prefix` + `potcars`/`orb_files`/`deepks_desc`.
+```json
+	"interaction": {
+		"type":		"abacus",
+		"incar":	"abacus_input/INPUT",
+		"potcar_prefix":"abacus_input",
+		"potcars":	{"Al": "pseudo_potential.al", "Mg": "pseudo_potential.mg"},
+		"orb_files": {"Al": "numerical_orb.al", "Mg": "numerical_orb.mg"},
+		"atom_masses": {"Al": 26.9815, "Mg":24.305},
+		"deepks_desc": "jle.orb"
+	}
+```
+**deepmd**:
+
+**Only 1** model can be used in autotest in one working directory.
+
+```json
+	"interaction": {
+		"type":		 "deepmd",
+		"model":	 "frozen_model.pb", 
+		"type_map":      {"Al": 0, "Mg": 1}
+	}
+```
+**meam**:
+
+Please make sure the [USER-MEAMC package](https://lammps.sandia.gov/doc/Packages_details.html#pkg-user-meamc) has already been installed in LAMMPS.
+```json
+	"interaction": {
+		"type":		 "meam",
+		"model":	 ["meam.lib","AlMg.meam"],
+		"type_map":      {"Al": 1, "Mg": 2}
+	}
+```
+**eam_fs & eam_alloy**:
+
+Please make sure the [MANYBODY package](https://lammps.sandia.gov/doc/Packages_details.html#pkg-manybody) has already been installed in LAMMPS
+```json
+	"interaction": {
+		"type":		 "eam_fs (eam_alloy)", 
+		"model":	 "AlMg.eam.fs (AlMg.eam.alloy)", 
+		"type_map":      {"Al": 1, "Mg": 2}
+	}
+```
+
+### Property type
+
+Now the supported property types are `eos`, `elastic`, `vacancy`, `interstitial`, `surface`, and `gamma`. Before property tests, `relaxation` should be done first or the relaxation results should be present in the corresponding directory `confs/mp-*/relaxation/relax_task`. A file named `task.json` in json format containing the property parameter will be written in the directory of each task after `make` step. Multiple property tests can be performed simultaneously.
+
+## Make run and post
+
+There are three operations in auto test package, namely `make`, `run`, and `post`. Here we take `eos` property as an example for property type.
+
+### Make
+The `INCAR`, `POSCAR`, `POTCAR` input files for VASP or `in.lammps`, `conf.lmp`, and the interatomic potential files for LAMMPS will be generated in the directory `confs/mp-*/relaxation/relax_task` for relaxation or `confs/mp-*/eos_00/task.[0-9]*[0-9]` for EOS. The `machine.json` file is not needed for `make`. Example: 
+```bash
+dpgen autotest make relaxation.json 
+```
+
+### Run
+The jobs would be dispatched according to the parameter in `machine.json` file and the calculation results would be sent back. Example:
+```bash
+dpgen autotest run relaxation.json machine.json
+```
+
+### Post
+The post process of calculation results would be performed. `result.json` in json format will be generated in `confs/mp-*/relaxation/relax_task` for relaxation and `result.json` in json format and `result.out` in txt format in `confs/mp-*/eos_00` for EOS. The `machine.json` file is also not needed for `post`. Example:
+```bash
+dpgen autotest post relaxation.json 
+```

doc/autotest/index.rst

@@ -0,0 +1,53 @@
+==========================
+Auto test
+==========================
+
+.. _Guidelines::
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Guidelines
+
+   Auto-test
+
+.. _Main-components::
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Main components
+
+   Task-type
+   Property-type
+   Make-run-and-post
+
+.. _Structure-relaxation::
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Structure relaxation
+
+   relaxation/index.rst
+
+.. _Property::
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Property
+
+   property/index.rst
+
+.. _Refine::
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Refine
+
+   refine/index.rst
+
+.. _Reproduce::
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Reproduce
+
+   reproduce/index.rst

doc/autotest/property/Property-get-started-and-input-examples.md

@@ -0,0 +1,119 @@
+## Property get started and input examples
+
+Here we take deepmd for example and the input file for other task types is similar.
+
+```json
+{
+    "structures":       ["confs/std-*"],
+    "interaction": {
+        "type":          "deepmd",
+        "model":         "frozen_model.pb",
+        "type_map":     {"Al": 0}
+    },
+    "properties": [
+        {
+         "type":         "eos",
+         "vol_start":    0.9,
+         "vol_end":      1.1,
+         "vol_step":     0.01
+        },
+        {
+         "type":         "elastic",
+         "norm_deform":  1e-2,
+         "shear_deform": 1e-2
+        },
+        {
+         "type":             "vacancy",
+         "supercell":        [3, 3, 3],
+         "start_confs_path": "../vasp/confs"
+        },
+        {
+         "type":         "interstitial",
+         "supercell":   [3, 3, 3],
+         "insert_ele":  ["Al"],
+         "conf_filters":{"min_dist": 1.5},
+         "cal_setting": {"input_prop": "lammps_input/lammps_high"}
+        },
+        {
+         "type":           "surface",
+         "min_slab_size":  10,
+         "min_vacuum_size":11,
+         "max_miller":     2,
+         "cal_type":       "static"
+        },
+        {
+         "type": "gamma",
+         "lattice_type": "fcc",
+         "miller_index": [1, 1, 1],
+         "displace_direction": [1, 1, 0],
+         "supercell_size": [1, 1, 10],
+         "min_vacuum_size": 10,
+         "add_fix": ["true", "true", "false"],
+         "n_steps": 20
+        }
+        ]
+}
+```
+Universal key words for properties
+
+Key words | data structure | example | description
+---|---|---|---
+**type** | String | "eos" | property type
+skip | Boolean | true | whether to skip current property or not
+start_confs_path | String | "../vasp/confs" | start from the equilibrium configuration in other path only for the current property type
+cal_setting["input_prop"] | String | "lammps_input/lammps_high" |input commands file 
+cal_setting["overwrite_interaction"] | Dict | | overwrite the interaction in the `interaction` part only for the current property type
+
+other parameters in `cal_setting` and `cal_type` in `relaxation` also apply in `property`.
+
+Key words for **EOS**
+
+Key words | data structure | example | description
+---|---|---|---
+**vol_start** | Float | 0.9 | the starting volume related to the equilibrium structure
+**vol_end** | Float | 1.1 | the biggest volume related to the equilibrium structure
+**vol_step** | Float | 0.01 | the volume increment related to the equilibrium structure
+vol_abs | Boolean | false | whether to treat vol_start, vol_end and vol_step as absolute volume or not (as relative volume), default = false
+
+Key words for **Elastic**
+
+Key words | data structure | example | description
+---|---|---|---
+norm_deform | Float | 1e-2 | deformation in xx, yy, zz, default = 1e-2
+shear_deform | Float | 1e-2 | deformation in other directions, default = 1e-2
+
+Key words for **Vacancy**
+
+Key words | data structure | example | description
+---|---|---|---
+supercell | List of Int | [3,3,3] | the supercell to be constructed, default = [1,1,1]
+
+Key words for **Interstitial**
+
+Key words | data structure | example | description
+---|---|---|---
+**insert_ele** | List of String | ["Al"] | the element to be inserted
+supercell | List of Int | [3,3,3] | the supercell to be constructed, default = [1,1,1]
+conf_filters | Dict | "min_dist": 1.5 | filter out the undesirable configuration
+bcc_self | Boolean | false | whether to do the self-interstitial calculations for bcc structures, default = false
+
+Key words for **Surface**
+
+Key words | data structure | example | description
+---|---|---|---
+**min_slab_size** | Int | 10 | minimum size of slab thickness
+**min_vacuum_size** | Int | 11 | minimum size of vacuum width
+pert_xz | Float | 0.01 | perturbation through xz direction used to compute surface energy, default = 0.01
+max_miller | Int | 2 | the maximum miller index, default = 2
+
+Key words for **Gamma**
+
+Key words | data structure | example | description
+---|---|---|---
+**lattice_type** | String | "fcc" | "bcc" or "fcc" at this stage
+**miller_index** | List of Int | [1,1,1] | slip plane for gamma-line calculation
+**displace_direction** | List of Int | [1,1,0] | slip direction for gamma-line calculation
+supercell_size | List of Int | [1,1,10] | the supercell to be constructed, default = [1,1,5]
+min_vacuum_size | Int or Float | 10 | minimum size of vacuum width, default = 20
+add_fix | List of String | ['true','true','false'] | whether to fix atoms in the direction, default = ['true','true','false'] (standard method)
+n_steps | Int | 20 | Number of points for gamma-line calculation, default = 10