fix out-dated docs. add explanation for configrations and convergence…

… methods

docs/index.rst

@@ -16,7 +16,7 @@ DPGEN2 is the 2nd generation of the Deep Potential GENerator.
    cli
    input.md
    submit_args
-   dpgen2_configs
+..   dpgen2_configs
 
 .. _developer-guide:
 

docs/input.md

@@ -51,9 +51,7 @@ This section defines how a model is trained.
 	"type" : "dp",
 	"numb_models" : 4,
 	"config" : {},
-	"template_script" : {
-		"_comment" : "omitted content of tempalte script"
-	},
+	"template_script" : "/path/to/the/template/input.json",
 	"_comment" : "all"
 }
 ```
@@ -71,11 +69,15 @@ This section defines how the configuration space is explored.
 	"config" : {
 		"command": "lmp -var restart 0"
 	},
+	"convergence": {
+	    "type" :	"fixed-levels",
+	    "conv_accuracy" :	0.9,
+	    "level_f_lo":	0.05,
+	    "level_f_hi":	0.50,
+	    "_comment" : "all"
+	},
 	"max_numb_iter" :	5,
-	"conv_accuracy" :	0.9,
 	"fatal_at_max" :	false,
-	"f_trust_lo":		0.05,
-	"f_trust_hi":		0.50,
 	"configurations":	[
 		{
 		"lattice" : ["fcc", 4.57],
@@ -124,7 +126,7 @@ The `"configurations"` provides the initial configurations (coordinates of atoms
 - `list[str]`: The strings provides the path to the configuration files.
 - `dict`: Automatic alloy configuration generator. See [the detailed doc](alloy_configs) of 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 [the full documentation of the target group](task_group_configs) for writting task groups.
+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 [the full documentation of the task group](task_group_configs) 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.
 

docs/submit_args.rst

@@ -5,3 +5,11 @@ Arguments of the submit script
 .. dargs::
    :module: dpgen2.entrypoint.args
    :func: submit_args
+
+
+Task group definition
+------------------
+.. _task_group_configs:
+.. dargs::
+   :module: dpgen2.exploration.task
+   :func: task_group_args

dpgen2/conf/alloy_conf.py

@@ -95,12 +95,25 @@ def generate(
             ms.append(ss)
         return ms
 
+    @staticmethod
+    def doc() -> str:
+        from dpgen2.entrypoint.args import (
+            make_link,
+        )
+
+        return f"Generate alloys with {make_link('a certain lattice or user proided structure', 'explore[lmp]/configurations[alloy]/lattice')}, the elements randomly occuping the lattice with {make_link('user provided probability', 'explore[lmp]/configurations[alloy]/concentration')} ."
+
     @staticmethod
     def args() -> List[Argument]:
+        from dpgen2.entrypoint.args import (
+            make_link,
+        )
+
+        link_to_type_map = make_link("type_map", "inputs/type_map")
         doc_numb_confs = "The number of configurations to generate"
-        doc_lattice = 'The lattice. Should be a list providing [ "lattice_type", lattice_const ], or a list providing [ "/path/to/dpdata/system", "fmt" ]. The two styles are distinguished by the type of the second element.'
+        doc_lattice = 'The lattice. Should be a list providing [ "lattice_type", lattice_const ], or a list providing [ "/path/to/dpdata/system", "fmt" ]. The two styles are distinguished by the type of the second element. Currently "lattice_type" can be "bcc", "fcc", "hcp", "sc" or "diamond".'
         doc_replicate = "The number of replicates in each direction"
-        doc_concentration = "The concentration of each element. If None all elements have the same concentration"
+        doc_concentration = f"The concentration of each element. `List[List[float]]` or `List[float]` or `None`. If `List[float]`, the concentrations of each element. The length of the list should be the same as the {link_to_type_map}. If `List[List[float]]`, a list of concentrations (`List[float]`) is randomly picked from the List. If `None`, the elements are assumed to be of equal concentration."
         doc_cell_pert_frac = "The faction of cell perturbation"
         doc_atom_pert_dist = "The distance of atomic position perturbation"
 

dpgen2/conf/file_conf.py

@@ -81,6 +81,10 @@ def generate_mixed(
         ms.from_deepmd_npy_mixed(self.files[0], fmt="deepmd/npy/mixed", labeled=False)  # type: ignore
         return ms
 
+    @staticmethod
+    def doc() -> str:
+        return "Generate alloys from user provided file(s). The file(s) are assume to be load by `dpdata`."
+
     @staticmethod
     def args() -> List[Argument]:
         doc_files = "The paths to the configuration files. widecards are supported."

dpgen2/entrypoint/args.py

@@ -31,6 +31,16 @@
 )
 
 
+def make_link(content, ref_key):
+    try:
+        raw_anchor = dargs.RAW_ANCHOR
+    except AttributeError:
+        raw_anchor = dargs.dargs.RAW_ANCHOR
+    return (
+        f"`{content} <{ref_key}_>`_" if not raw_anchor else f"`{content} <#{ref_key}>`_"
+    )
+
+
 def dp_dist_train_args():
     doc_config = "Configuration of training"
     doc_template_script = "File names of the template training script. It can be a `List[str]`, the length of which is the same as `numb_models`. Each template script in the list is used to train a model. Can be a `str`, the models share the same template training script. "
@@ -97,10 +107,17 @@ def variant_train():
 
 
 def variant_conv():
-    doc = "the type of the convergence check"
+    doc = "the type of the condidate selection and convergence check method."
     var_list = []
     for kk in conv_styles.keys():
-        var_list.append(Argument(kk, dict, conv_styles[kk].args()))
+        var_list.append(
+            Argument(
+                kk,
+                dict,
+                conv_styles[kk].args(),
+                doc=conv_styles[kk].doc(),
+            )
+        )
     return Variant(
         "type",
         var_list,
@@ -109,10 +126,17 @@ def variant_conv():
 
 
 def variant_conf():
-    doc = "the type of the configuration generator"
+    doc = "the type of the initial configuration generator."
     var_list = []
     for kk in conf_styles.keys():
-        var_list.append(Argument(kk, dict, conf_styles[kk].args()))
+        var_list.append(
+            Argument(
+                kk,
+                dict,
+                conf_styles[kk].args(),
+                doc=conf_styles[kk].doc(),
+            )
+        )
     return Variant(
         "type",
         var_list,
@@ -130,7 +154,12 @@ def lmp_args():
     doc_convergence = "The method of convergence check."
     doc_configuration_prefix = "The path prefix of lmp initial configurations"
     doc_configuration = "A list of initial configurations."
-    doc_stages = "A list of exploration stages."
+    doc_stages = (
+        "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` "
+    )
 
     return [
         Argument(
@@ -158,13 +187,6 @@ def lmp_args():
             optional=False,
             doc=doc_convergence,
         ),
-        Argument(
-            "configuration_prefix",
-            str,
-            optional=True,
-            default=None,
-            doc=doc_configuration_prefix,
-        ),
         Argument(
             "configurations",
             list,
@@ -180,11 +202,12 @@ def lmp_args():
 
 
 def variant_explore():
-    doc = "the type of the exploration"
+    doc = "The type of the exploration"
+    doc_lmp = "The exploration by LAMMPS simulations"
     return Variant(
         "type",
         [
-            Argument("lmp", dict, lmp_args()),
+            Argument("lmp", dict, lmp_args(), doc=doc_lmp),
         ],
         doc=doc,
     )
@@ -234,15 +257,16 @@ def input_args():
     doc_type_map = 'The type map. e.g. ["Al", "Mg"]. Al and Mg will have type 0 and 1, respectively.'
     doc_mass_map = "The mass map. e.g. [27., 24.]. Al and Mg will be set with mass 27. and 24. amu, respectively."
     doc_mixed_type = "Use `deepmd/npy/mixed` format for storing training data."
-    doc_do_finetune = """Finetune the pretrained model before the first iteration. If it is set to True, then an additional step, finetune-step,
-                       which is based on a branch of "PrepRunDPTrain," will be added before the dpgen_step. In the
-                       finetune-step, the internal flag finetune_mode is set to "finetune," which means SuperOP "PrepRunDPTrain"
-                       is now used as the "Finetune." In this step, we finetune the pretrained model in the train step and modify
-                       the template after training. After that, in the normal dpgen-step, the flag do_finetune is set as "train-init,"
-                       which means we use --init-frz-model to train based on models from the previous iteration. The "do_finetune" flag
-                       is set to False by default, while the internal flag finetune_mode is set to "no," which means anything related
-                       to finetuning will not be done.
-                       """
+    doc_do_finetune = (
+        "Finetune the pretrained model before the first iteration. If it is set to True, then an additional step, finetune-step, "
+        'which is based on a branch of "PrepRunDPTrain," will be added before the dpgen_step. In the '
+        'finetune-step, the internal flag finetune_mode is set to "finetune," which means SuperOP "PrepRunDPTrain" '
+        'is now used as the "Finetune." In this step, we finetune the pretrained model in the train step and modify '
+        'the template after training. After that, in the normal dpgen-step, the flag do_finetune is set as "train-init," '
+        'which means we use `--init-frz-model` to train based on models from the previous iteration. The "do_finetune" flag '
+        'is set to False by default, while the internal flag finetune_mode is set to "no," which means anything related '
+        "to finetuning will not be done."
+    )
     doc_do_finetune = textwrap.dedent(doc_do_finetune)
     doc_init_data_prefix = "The prefix of initial data systems"
     doc_init_sys = "The inital data systems"

dpgen2/exploration/report/report_adaptive_lower.py

@@ -128,6 +128,27 @@ def __init__(
         self.fmt_flt = "%.4f"
         self.header_str = "#" + self.fmt_str % print_tuple
 
+    @staticmethod
+    def doc() -> str:
+        def make_class_doc_link(key):
+            from dpgen2.entrypoint.args import (
+                make_link,
+            )
+
+            return make_link(key, f"explore[lmp]/convergence[adaptive-lower]/{key}")
+
+        numb_candi_f_link = make_class_doc_link("numb_candi_f")
+        rate_candi_f_link = make_class_doc_link("rate_candi_f")
+        numb_candi_v_link = make_class_doc_link("numb_candi_v")
+        rate_candi_v_link = make_class_doc_link("rate_candi_v")
+        numb_candi_s = f"{numb_candi_f_link} or {numb_candi_v_link}"
+        rate_candi_s = f"{rate_candi_f_link} or {rate_candi_v_link}"
+        level_f_hi_link = make_class_doc_link("level_f_hi")
+        level_v_hi_link = make_class_doc_link("level_v_hi")
+        conv_tolerance_link = make_class_doc_link("conv_tolerance")
+        n_checked_steps_link = make_class_doc_link("n_checked_steps")
+        return f"The method of adaptive adjust the lower trust levels. In each step of iterations, a number (set by {numb_candi_s}) or a ratio (set by {rate_candi_s}) of configurations with a model deviation lower than the higher trust level ({level_f_hi_link}, {level_v_hi_link}) are treated as candidates. The lowest model deviation of the candidates are treated as the lower trust level. If the lower trust level does not change significant (controlled by {conv_tolerance_link}) in {n_checked_steps_link}, the stage is treated as converged. "
+
     @staticmethod
     def args() -> List[Argument]:
         doc_level_f_hi = "The higher trust level of force model deviation"

dpgen2/exploration/report/report_trust_levels_max.py

@@ -89,3 +89,21 @@ def _get_candidates(
         else:
             ret = self.traj_cand_picked
         return ret
+
+    @staticmethod
+    def doc() -> str:
+        def make_class_doc_link(key):
+            from dpgen2.entrypoint.args import (
+                make_link,
+            )
+
+            return make_link(
+                key, f"explore[lmp]/convergence[fixed-levels-max-select]/{key}"
+            )
+
+        level_f_hi_link = make_class_doc_link("level_f_hi")
+        level_v_hi_link = make_class_doc_link("level_v_hi")
+        level_f_lo_link = make_class_doc_link("level_f_lo")
+        level_v_lo_link = make_class_doc_link("level_v_lo")
+        conv_accuracy_link = make_class_doc_link("conv_accuracy")
+        return f"The configurations with force model deviation between {level_f_lo_link}, {level_f_hi_link} or virial model deviation between {level_v_lo_link} and {level_v_hi_link} are treated as candidates (The virial model deviation check is optional). The configurations with maximal model deviation in the candidates are sent for FP calculations. If the ratio of accurate (below {level_f_lo_link} and {level_v_lo_link}) is higher then {conv_accuracy_link}, the stage is treated as converged."

dpgen2/exploration/report/report_trust_levels_random.py

@@ -83,3 +83,19 @@ def _get_candidates(
         else:
             ret = self.traj_cand_picked
         return ret
+
+    @staticmethod
+    def doc() -> str:
+        def make_class_doc_link(key):
+            from dpgen2.entrypoint.args import (
+                make_link,
+            )
+
+            return make_link(key, f"explore[lmp]/convergence[fixed-levels]/{key}")
+
+        level_f_hi_link = make_class_doc_link("level_f_hi")
+        level_v_hi_link = make_class_doc_link("level_v_hi")
+        level_f_lo_link = make_class_doc_link("level_f_lo")
+        level_v_lo_link = make_class_doc_link("level_v_lo")
+        conv_accuracy_link = make_class_doc_link("conv_accuracy")
+        return f"The configurations with force model deviation between {level_f_lo_link}, {level_f_hi_link} or virial model deviation between {level_v_lo_link} and {level_v_hi_link} are treated as candidates (The virial model deviation check is optional). The configurations will be randomly sampled from candidates for FP calculations. If the ratio of accurate (below {level_f_lo_link} and {level_v_lo_link}) is higher then {conv_accuracy_link}, the stage is treated as converged."

examples/almg/input.json

@@ -127,9 +127,10 @@
     "train":{
 	"type" :	"dp",
 	"numb_models" : 4,
-	"config" : {},
-	"template_script" : {
+	"config" : {
+	    "init_model_policy" : "no"
 	},
+	"template_script" : "dp_template.json",
 	"_comment" : "all"
     },
 
@@ -148,7 +149,6 @@
 	"max_numb_iter" :	5,
 	"fatal_at_max" :	false,
 	"output_nopbc":		false,
-	"configuration_prefix": null,
 	"configurations":	[
 	    {
 		"type": "alloy",