[Documentation] Add comprehensive CALYPSO model_devi arguments

dpgen/generator/arginfo.py

@@ -593,16 +593,91 @@ 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 corresponds to one or more iterations. "
+        "If not provided, `calypso_input_path` must be specified to use external input.dat files."
+    )
+    doc_times = "List of iteration indices when this job should be executed."
+    doc_nameofatoms = "Element symbols of the different 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 will determine automatically."
+    doc_distanceofion = "2D matrix of minimal distances between atoms of each chemical species (angstrom). Shape should match number of species."
+    doc_psoratio = "Proportion of structures generated by PSO algorithm (0.0-1.0). Default is 0.6."
+    doc_popsize = "Population size for structure generation. Larger values recommended for complex systems."
+    doc_maxstep = "Maximum number of optimization steps in CALYPSO iteration."
+    doc_icode = "Interface code for local optimization: 1=VASP, 2=SIESTA, 3=GULP."
+    doc_split = "Whether to split calculations. 'T' for true, 'F' for false."
+    doc_vsc = "Variable Stoichiometry Control. 'T' to enable, 'F' to disable."
+    doc_maxnumatom = "Maximum number of atoms in unit cell (required when VSC='T')."
+    doc_ctrlrange = "2D list defining variation range for each atom type when VSC='T'. Shape should match number of species."
+    doc_pstress = "Target pressure(s) in GPa. Can be single value or list for multiple pressures."
+    doc_fmax = "Force convergence criterion for local optimization (eV/angstrom)."
+
+    doc_calypso_input_path = (
+        "Path to directory containing pre-existing CALYPSO input.dat files. "
+        "Alternative to defining model_devi_jobs. When used, structures will be generated "
+        "according to the provided input files instead of job specifications."
+    )
+    doc_model_devi_max_iter = (
+        "Maximum number of iterations when using calypso_input_path mode. "
+        "Required when calypso_input_path is specified."
+    )
+    doc_vsc_mode = "Enable variable stoichiometry mode when using external input files."
+
+    return [
+        # Option 1: Native job configuration mode
+        Argument(
+            "model_devi_jobs",
+            list,
+            optional=True,
+            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, list[float]], optional=True, doc=doc_volume),
+                Argument("DistanceOfIon", list[list[float]], optional=False, doc=doc_distanceofion),
+                Argument("PsoRatio", [float, list[float]], optional=True, default=0.6, doc=doc_psoratio),
+                Argument("PopSize", [int, list[int]], optional=True, default=30, doc=doc_popsize),
+                Argument("MaxStep", [int, list[int]], optional=True, default=5, doc=doc_maxstep),
+                Argument("ICode", [int, list[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, list[int]], optional=True, doc=doc_maxnumatom),
+                Argument("CtrlRange", list[list[int]], optional=True, doc=doc_ctrlrange),
+                Argument("PSTRESS", [float, list[float]], optional=True, default=[0.001], doc=doc_pstress),
+                Argument("fmax", [float, list[float]], optional=True, default=0.01, doc=doc_fmax),
+            ],
+        ),
+        # Option 2: External input.dat file mode
+        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),
+    ]
+
+
 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. "
+        "CALYPSO can generate structures either from user-defined job specifications "
+        "or from external input.dat files. It supports variable stoichiometry control "
+        "and multiple pressure conditions for materials discovery."
+    )
     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",