Skip to content

fix(generator): document CALYPSO model deviation args #1886

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
njzjz-bot wants to merge 1 commit into
base: master
Choose a base branch
from
Open

fix(generator): document CALYPSO model deviation args #1886

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
225 changes: 224 additions & 1 deletion dpgen/generator/arginfo.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
),
Comment on lines +743 to +746

@coderabbitai coderabbitai Bot Jun 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

calypso_input_path mode can pass validation but still fail at runtime

model_devi_max_iter is optional here, but make_model_devi() uses it as the iteration bound when calypso_input_path is present. This allows a config that passes arginfo and then crashes/fails during iteration bound handling in CALYPSO mode. Please enforce this as a conditional requirement (calypso_input_path => model_devi_max_iter) in schema validation or via explicit early validation in the CALYPSO run path.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dpgen/generator/arginfo.py` around lines 743 - 746, The Argument definition
for "model_devi_max_iter" is marked as optional=True, but it is required when
"calypso_input_path" is present, causing configs to pass validation but fail at
runtime in make_model_devi(). Either remove the optional=True flag to make
"model_devi_max_iter" always required, or add conditional validation logic that
enforces "model_devi_max_iter" as a required field specifically when
"calypso_input_path" is provided. Ensure the validation occurs early enough to
prevent runtime failures during CALYPSO execution.

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",
Expand Down