improve the doc

wanghan-iapcm · Oct 12, 2023 · 762d036 · 762d036
1 parent dac8d80
commit 762d036
Show file tree

Hide file tree

Showing 6 changed files with 41 additions and 36 deletions.
diff --git a/docs/input.md b/docs/input.md
@@ -40,7 +40,7 @@ This section provides the inputs to start a dpgen2 workflow. An example for the
 	],
 }
 ```
-The key `"init_data_sys"` provides the initial training data to kick-off the training of deep potential (DP) models.
+The key {dargs:argument}`"init_data_sys" <inputs/init_data_sys>` provides the initial training data to kick-off the training of deep potential (DP) models.
 
 
 ### Training
@@ -55,9 +55,9 @@ This section defines how a model is trained.
 	"_comment" : "all"
 }
 ```
-The `"type" : "dp"` tell the traning method is `"dp"`, i.e. calling [DeePMD-kit](https://github.com/deepmodeling/deepmd-kit) to train DP models.
-The `"config"` key defines the training configs, see [the full documentation](rundptrainargs).
-The `"template_script"` provides the template training script in `json` format.
+The `"type" : "dp"` tell the traning method is {dargs:argument}`"dp" <train>`, i.e. calling [DeePMD-kit](https://github.com/deepmodeling/deepmd-kit) to train DP models.
+The `"config"` key defines the training configs, see {ref}`the full documentation<train[dp]/config>`.
+The {dargs:argument}`"template_script" <train[dp]/template_script>` provides the template training script in `json` format.
 
 
 ### Exploration
@@ -80,16 +80,16 @@ This section defines how the configuration space is explored.
 	"fatal_at_max" :	false,
 	"configurations":	[
 		{
+		"type": "alloy",
 		"lattice" : ["fcc", 4.57],
 		"replicate" : [2, 2, 2],
 		"numb_confs" : 30,
 		"concentration" : [[1.0, 0.0], [0.5, 0.5], [0.0, 1.0]]
 		}
 		{
-		"lattice" : ["fcc", 4.57],
-		"replicate" : [3, 3, 3],
-		"numb_confs" : 30,
-		"concentration" : [[1.0, 0.0], [0.5, 0.5], [0.0, 1.0]]
+		"type" : "file",
+		"files" : ["/path/to/confs/*"],
+		"fmt" : "deepmd/npy"
 		}
 	],
 	"stages":	[
@@ -101,7 +101,7 @@ This section defines how the configuration space is explored.
 		    "conf_idx": [0], "n_sample" : 3
 		},
 		{
-		    "_comment" : "stage 1, task group 0",
+		    "_comment" : "stage 0, task group 1",
 		    "type" : "lmp-template",
 		    "lmp" : "template.lammps", "plm" : "template.plumed",
 		    "trj_freq" : 10, "revisions" : {"V_NSTEPS" : [40], "V_TEMP" : [150, 200]},
@@ -119,16 +119,16 @@ This section defines how the configuration space is explored.
 	],
 }
 ```
-The `"type" : "lmp"` means that configurations are explored by LAMMPS DPMD runs.
-The `"config"` key defines the lmp configs, see {ref}`the full documentation<explore[lmp]/config>`.
-The `"configurations"` provides the initial configurations (coordinates of atoms and the simulation cell) of the DPMD simulations. It is a list. The elements of the list can be
+The {dargs:argument}`"type" : "lmp"<explore>` means that configurations are explored by LAMMPS DPMD runs.
+The {dargs:argument}`"config"<explore[lmp]/config>` key defines the lmp configs.
+The {dargs:argument}`"configurations"<explore[lmp]/configurations>` provides the initial configurations (coordinates of atoms and the simulation cell) of the DPMD simulations. It is a list. The elements of the list are `dict`s that defines how the configurations are generated
 
-- `list[str]`: The strings provides the path to the configuration files.
-- `dict`: Automatic alloy configuration generator. See {ref}`the detailed doc<explore[lmp]/configurations[alloy]>` of the allowed keys.
+- Automatic alloy configuration generator. See {ref}`the detailed doc<explore[lmp]/configurations[alloy]>` for the allowed keys.
+- Configurations load from files. See {ref}`the detailed doc<explore[lmp]/configurations[file]>` for the allowed keys.
 
-The `"stages"` defines the exploration stages. It is of type `list[list[dict]]`. The outer `list` enumerate the exploration stages, the inner list enumerate the task groups of the stage. Each `dict` defines a stage. See {ref}`the full documentation of the task group<task_group_configs>` for writting task groups.
+The {dargs:argument}`"stages"<explore[lmp]/stages>` defines the exploration stages. It is of type `list[list[dict]]`. The outer `list` enumerate the exploration stages, the inner list enumerate the task groups of the stage. Each `dict` defines a stage. See {ref}`the full documentation of the task group<task_group_sec>` for writting task groups.
 
-`"n_sample"` tells the number of confgiruations randomly sampled from the set picked by `"conf_idx"` from `configurations` for each exploration task. All configurations has the equal possibility to be sampled. The default value of `"n_sample"` is `null`, in this case all picked configurations are sampled. In the example, we have 3 samples for stage 0 task group 0 and 2 thermodynamic states (NVT, T=50 and 100K), then the task group has 3x2=6 NVT DPMD tasks.
+The {dargs:argument}`"n_sample"<task_group[lmp-md]/n_sample>` tells the number of confgiruations randomly sampled from the set picked by {dargs:argument}`"conf_idx"<task_group[lmp-md]/conf_idx>` from {dargs:argument}`"configurations"<explore[lmp]/configurations>` for each exploration task. All configurations has the equal possibility to be sampled. The default value of `"n_sample"` is `null`, in this case all picked configurations are sampled. In the example, we have 3 samples for stage 0 task group 0 and 2 thermodynamic states (NVT, T=50 and 100K), then the task group has 3x2=6 NVT DPMD tasks.
 
 
 ### FP
@@ -137,25 +137,27 @@ This section defines the first-principle (FP) calculation .
 
 ```json
 "fp" : {
-	"type" :	"vasp",
-	"config" : {
+	"type": "vasp",
+    "task_max":	2,
+	"run_config": {
 		"command": "source /opt/intel/oneapi/setvars.sh && mpirun -n 16 vasp_std"
 	},
-	"task_max":	2,
-	"pp_files":	{"Al" : "vasp/POTCAR.Al", "Mg" : "vasp/POTCAR.Mg"},
-	"incar":         "vasp/INCAR",
-	"_comment" : "all"
+	"inputs_config": {
+		"pp_files":	{"Al" : "vasp/POTCAR.Al", "Mg" : "vasp/POTCAR.Mg"},
+	    "kspacing":	0.32,
+		"incar": "vasp/INCAR"
+	}
 }
 ```
-The `"type" : "vasp"` means that first-principles are VASP calculations.
-The `"config"` key defines the vasp configs, see [the full documentation](runvaspargs).
-The `"task_max"` key defines the maximal number of vasp calculations in each dpgen2 iteration.
-The `"pp_files"` and `"incar"` keys provides the pseudopotential files and the template incar file.
+The {dargs:argument}`"type" : "vasp"<fp>` means that first-principles are VASP calculations.
+The {dargs:argument}`"run_config"<fp[vasp]/run_config>` key defines the configs for running VASP tasks.
+The {dargs:argument}`"task_max"<fp[vasp]/task_max>` key defines the maximal number of vasp calculations in each dpgen2 iteration.
+The {dargs:argument}`"pp_files"<fp[vasp]/inputs_config/pp_files>`, {dargs:argument}`"kspacing"<fp[vasp]/inputs_config/kspacing>` and {dargs:argument}`"incar"<fp[vasp]/inputs_config/incar>` keys provides the pseudopotential files, spacing for kspace sampling and the template incar file, respectively.
 
 
 ### Configuration of dflow step
 
-The execution units of the dpgen2 are the dflow `Step`s. How each step is executed is defined by the `"step_configs"`.
+The execution units of the dpgen2 are the dflow `Step`s. How each step is executed is defined by the {dargs:argument}`"step_configs"<step_configs>`.
 ```json
 "step_configs":{
 	"prep_train_config" : {
@@ -190,14 +192,12 @@ The execution units of the dpgen2 are the dflow `Step`s. How each step is execut
 ```
 The configs for prepare training, run training, prepare exploration, run exploration, prepare fp, run fp, select configurations, collect data and concurrent learning steps are given correspondingly.
 
-The readers are refered to [this page](stepconfigargs) for a full documentation of the step configs.
-
-Any of the config in the `step_configs` can be ommitted. If so, the configs of the step is set to the default step configs, which is provided by the following section, for example,
+Any of the config in the {dargs:argument}`"step_configs"<step_configs>` can be ommitted. If so, the configs of the step is set to the default step configs, which is provided by the following section, for example,
 ```json
 "default_step_config" : {
 	"template_config" : {
 	    "image" : "dpgen2:x.x.x"
 	}
 },
 ```
-The way of writing the `default_step_config` is the same as any step config in the `step_configs`. One may refer to [this page](stepconfigargs) for full documentation.
+The way of writing the {dargs:argument}`"default_step_config"<default_step_config>` is the same as any step config in the {dargs:argument}`"step_configs"<step_configs>`.
diff --git a/docs/submit_args.rst b/docs/submit_args.rst
@@ -1,13 +1,14 @@
+.. _submitargs:
+
 Arguments of the submit script
 ==============================
 
-.. _submitargs:
 .. dargs::
    :module: dpgen2.entrypoint.args
    :func: submit_args
 
 
-.. _task_group_configs:
+.. _task_group_sec:
 
 Task group definition
 ------------------

diff --git a/dpgen2/entrypoint/args.py b/dpgen2/entrypoint/args.py
@@ -155,7 +155,7 @@ def lmp_args():
         "The definition of exploration stages of type `List[List[ExplorationTaskGroup]`. "
         "The outer list provides the enumeration of the exploration stages. "
         "Then each stage is defined by a list of exploration task groups. "
-        "The definition of each task group is described in :ref:`Task group definition<task_group_configs>` "
+        "Each task group is described in :ref:`the task group definition<task_group_sec>` "
     )
 
     return [

diff --git a/dpgen2/exploration/task/make_task_group_from_config.py b/dpgen2/exploration/task/make_task_group_from_config.py
@@ -269,7 +269,7 @@ def variant_task_group():
 
 
 def task_group_args():
-    return Argument("task_group_configs", dict, [], [variant_task_group()])
+    return Argument("task_group", dict, [], [variant_task_group()])
 
 
 def normalize(data):

diff --git a/examples/almg/input.json b/examples/almg/input.json
@@ -156,6 +156,11 @@
 		"replicate" : [2, 2, 2],
 		"numb_confs" : 30,
 		"concentration" : [[1.0, 0.0], [0.5, 0.5], [0.0, 1.0]]
+	    },
+	    {
+		"type" : "file",
+		"files" : ["/path/to/confs/*"],
+		"fmt" : "deepmd/npy"
 	    }
 	],
 	"_comment" : "Stage is of type List[List[dict]]. ",

diff --git a/examples/chno/input.json b/examples/chno/input.json
@@ -166,7 +166,6 @@
 	"max_numb_iter" :	12,
 	"fatal_at_max" :	false,
 	"output_nopbc":		true,
-	"configuration_prefix": null,
 	"configurations":	[
 	    {
 		"type" : "file",