fix(generator): document CALYPSO model deviation args

Add CALYPSO-specific arginfo without accepting list-valued settings that the generator currently cannot consume, and keep the common model-deviation selection keys valid for CALYPSO runs.

Authored by OpenClaw (model: custom-chat-jinzhezeng-group/gpt-5.5)

Author: njzjz-bot

dpgen/generator/arginfo.py

@@ -621,16 +621,239 @@ def model_devi_amber_args() -> list[Argument]:
     ]
 
 
+def model_devi_calypso_args() -> list[Argument]:
+    """CALYPSO engine arguments."""
+    doc_model_devi_jobs = (
+        "Settings for CALYPSO structure generation and model deviation. "
+        "Each dict in the list describes the CALYPSO input used for one or more "
+        "iterations selected by `times`."
+    )
+    doc_times = "List of iteration indices when this CALYPSO job should be executed."
+    doc_nameofatoms = "Element symbols of the chemical species."
+    doc_numberofatoms = "Number of atoms for each chemical species in one formula unit."
+    doc_numberofformula = "Range of formula units per cell as [min, max]."
+    doc_volume = "Volume per formula unit in angstrom^3. If not provided, CALYPSO determines it automatically."
+    doc_distanceofion = "Minimal distances between atom types in angstrom. Shape should match the number of species."
+    doc_psoratio = (
+        "Proportion of structures generated by the PSO algorithm, between 0.0 and 1.0."
+    )
+    doc_popsize = "Population size for structure generation."
+    doc_maxstep = "Maximum number of CALYPSO optimization steps."
+    doc_icode = "CALYPSO interface code for local optimization, such as 1 for VASP."
+    doc_split = "Whether to split calculations. Use 'T' or 'F'."
+    doc_vsc = "Variable stoichiometry control. Use 'T' to enable or 'F' to disable."
+    doc_maxnumatom = (
+        "Maximum number of atoms in the unit cell. Required when VSC is 'T'."
+    )
+    doc_ctrlrange = "Variation range for each atom type. Required when VSC is 'T'."
+    doc_pstress = "Target pressure list in GPa. One CALYPSO input directory is created for each pressure."
+    doc_fmax = "Force convergence criterion for local optimization, in eV/angstrom."
+    doc_calypso_input_path = (
+        "Path to a directory containing pre-existing CALYPSO input.dat files. "
+        "When set, DP-GEN copies those files instead of generating input.dat from "
+        "the CALYPSO fields in model_devi_jobs."
+    )
+    doc_model_devi_max_iter = "Maximum iteration index when using calypso_input_path."
+    doc_vsc_mode = (
+        "Enable variable stoichiometry mode when using external CALYPSO input files."
+    )
+    doc_model_devi_dt = (
+        "Timestep retained for compatibility with existing CALYPSO parameter files."
+    )
+    doc_model_devi_skip = (
+        "Number of structures skipped during model deviation selection."
+    )
+    doc_model_devi_f_trust_lo = "Lower bound of force model deviation for selection."
+    doc_model_devi_f_trust_hi = "Upper bound of force model deviation for selection."
+    doc_model_devi_v_trust_lo = "Lower bound of virial model deviation for selection."
+    doc_model_devi_v_trust_hi = "Upper bound of virial model deviation for selection."
+    doc_model_devi_e_trust_lo = "Lower bound of energy model deviation for selection."
+    doc_model_devi_e_trust_hi = "Upper bound of energy model deviation for selection."
+    doc_model_devi_clean_traj = (
+        "Whether to clean large trajectory folders after model deviation."
+    )
+    doc_model_devi_adapt_trust_lo = (
+        "Adaptively determine the lower force and virial trust levels."
+    )
+    doc_model_devi_numb_candi_f = "See model_devi_adapt_trust_lo."
+    doc_model_devi_numb_candi_v = "See model_devi_adapt_trust_lo."
+    doc_model_devi_perc_candi_f = "See model_devi_adapt_trust_lo."
+    doc_model_devi_perc_candi_v = "See model_devi_adapt_trust_lo."
+    doc_model_devi_f_avg_relative = (
+        "Normalize force model deviations by the RMS force magnitude."
+    )
+    doc_use_relative = "Calculate relative force model deviation."
+    doc_epsilon = "Level parameter for computing the relative force model deviation."
+    doc_use_relative_v = "Calculate relative virial model deviation."
+    doc_epsilon_v = "Level parameter for computing the relative virial model deviation."
+
+    return [
+        Argument(
+            "model_devi_jobs",
+            list,
+            optional=False,
+            repeat=True,
+            doc=doc_model_devi_jobs,
+            sub_fields=[
+                Argument("times", list[int], optional=False, doc=doc_times),
+                Argument("NameOfAtoms", list[str], optional=False, doc=doc_nameofatoms),
+                Argument(
+                    "NumberOfAtoms", list[int], optional=False, doc=doc_numberofatoms
+                ),
+                Argument(
+                    "NumberOfFormula",
+                    list[int],
+                    optional=True,
+                    default=[1, 1],
+                    doc=doc_numberofformula,
+                ),
+                Argument("Volume", float, optional=True, doc=doc_volume),
+                Argument(
+                    "DistanceOfIon",
+                    list[list[float]],
+                    optional=False,
+                    doc=doc_distanceofion,
+                ),
+                Argument(
+                    "PsoRatio",
+                    float,
+                    optional=True,
+                    default=0.6,
+                    doc=doc_psoratio,
+                ),
+                Argument("PopSize", int, optional=True, default=30, doc=doc_popsize),
+                Argument("MaxStep", int, optional=True, default=5, doc=doc_maxstep),
+                Argument("ICode", int, optional=True, default=1, doc=doc_icode),
+                Argument("Split", str, optional=True, default="T", doc=doc_split),
+                Argument("VSC", str, optional=True, default="F", doc=doc_vsc),
+                Argument("MaxNumAtom", int, optional=True, doc=doc_maxnumatom),
+                Argument(
+                    "CtrlRange", list[list[int]], optional=True, doc=doc_ctrlrange
+                ),
+                Argument(
+                    "PSTRESS",
+                    list[float],
+                    optional=True,
+                    default=[0.001],
+                    doc=doc_pstress,
+                ),
+                Argument("fmax", float, optional=True, default=0.01, doc=doc_fmax),
+            ],
+        ),
+        Argument("calypso_input_path", str, optional=True, doc=doc_calypso_input_path),
+        Argument(
+            "model_devi_max_iter", int, optional=True, doc=doc_model_devi_max_iter
+        ),
+        Argument("vsc", bool, optional=True, default=False, doc=doc_vsc_mode),
+        Argument("model_devi_dt", float, optional=True, doc=doc_model_devi_dt),
+        Argument("model_devi_skip", int, optional=False, doc=doc_model_devi_skip),
+        Argument(
+            "model_devi_f_trust_lo",
+            [float, list[float], dict],
+            optional=False,
+            doc=doc_model_devi_f_trust_lo,
+        ),
+        Argument(
+            "model_devi_f_trust_hi",
+            [float, list[float], dict],
+            optional=False,
+            doc=doc_model_devi_f_trust_hi,
+        ),
+        Argument(
+            "model_devi_v_trust_lo",
+            [float, list[float], dict],
+            optional=True,
+            default=1e10,
+            doc=doc_model_devi_v_trust_lo,
+        ),
+        Argument(
+            "model_devi_v_trust_hi",
+            [float, list[float], dict],
+            optional=True,
+            default=1e10,
+            doc=doc_model_devi_v_trust_hi,
+        ),
+        Argument(
+            "model_devi_e_trust_lo",
+            [float, list[float], dict],
+            optional=True,
+            default=1e10,
+            doc=doc_model_devi_e_trust_lo,
+        ),
+        Argument(
+            "model_devi_e_trust_hi",
+            [float, list[float], dict],
+            optional=True,
+            default=1e10,
+            doc=doc_model_devi_e_trust_hi,
+        ),
+        Argument(
+            "model_devi_adapt_trust_lo",
+            bool,
+            optional=True,
+            doc=doc_model_devi_adapt_trust_lo,
+        ),
+        Argument(
+            "model_devi_numb_candi_f",
+            int,
+            optional=True,
+            doc=doc_model_devi_numb_candi_f,
+        ),
+        Argument(
+            "model_devi_numb_candi_v",
+            int,
+            optional=True,
+            doc=doc_model_devi_numb_candi_v,
+        ),
+        Argument(
+            "model_devi_perc_candi_f",
+            float,
+            optional=True,
+            doc=doc_model_devi_perc_candi_f,
+        ),
+        Argument(
+            "model_devi_perc_candi_v",
+            float,
+            optional=True,
+            doc=doc_model_devi_perc_candi_v,
+        ),
+        Argument(
+            "model_devi_f_avg_relative",
+            bool,
+            optional=True,
+            doc=doc_model_devi_f_avg_relative,
+        ),
+        Argument(
+            "model_devi_clean_traj",
+            [bool, int],
+            optional=True,
+            default=True,
+            doc=doc_model_devi_clean_traj,
+        ),
+        Argument(
+            "use_relative", bool, optional=True, default=False, doc=doc_use_relative
+        ),
+        Argument("epsilon", float, optional=True, doc=doc_epsilon),
+        Argument(
+            "use_relative_v", bool, optional=True, default=False, doc=doc_use_relative_v
+        ),
+        Argument("epsilon_v", float, optional=True, doc=doc_epsilon_v),
+    ]
+
+
 def model_devi_args() -> list[Variant]:
     doc_model_devi_engine = "Engine for the model deviation task."
     doc_amber = "Amber DPRc engine. The command argument in the machine file should be path to sander."
+    doc_calypso = (
+        "CALYPSO structure generation engine for crystal structure prediction."
+    )
     return [
         Variant(
             "model_devi_engine",
             [
                 Argument("lammps", dict, model_devi_lmp_args(), doc="LAMMPS"),
                 Argument("amber", dict, model_devi_amber_args(), doc=doc_amber),
-                Argument("calypso", dict, [], doc="TODO: add doc"),
+                Argument("calypso", dict, model_devi_calypso_args(), doc=doc_calypso),
                 Argument("gromacs", dict, [], doc="TODO: add doc"),
             ],
             default_tag="lammps",