feat: validate LAMMPS template revision variables before task execution

docs/input.md

@@ -106,6 +106,7 @@ This section defines how the configuration space is explored.
 		    "type" : "lmp-template",
 		    "lmp" : "template.lammps", "plm" : "template.plumed",
 		    "trj_freq" : 10, "revisions" : {"V_NSTEPS" : [40], "V_TEMP" : [150, 200]},
+		    "strict_revisions": true,
 		    "conf_idx": [0], "n_sample" : 3
 		}
 	    ],
@@ -120,6 +121,19 @@ This section defines how the configuration space is explored.
 	]
 }
 ```
+
+For an `"lmp-template"` task group, `revisions` keys are replaced as complete
+tokens in both LAMMPS and PLUMED templates. By default, `strict_revisions` is
+`false`: standalone `V_*` tokens not listed in `revisions` are preserved and
+reported as warnings because they may be native LAMMPS or PLUMED identifiers.
+Set `strict_revisions` to `true` to stop task generation when such tokens are
+found.
+
+For a `"customized-lmp-template"` task group, `strict_revisions` defaults to
+`false` for the same compatibility reason: its shell commands may intentionally
+generate templates containing `V_*` tokens. Set it to `true` to apply strict
+validation to the generated templates.
+
 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

dpgen2/exploration/task/customized_lmp_template_task_group.py

@@ -62,6 +62,7 @@ def set_lmp(
         output_lmp_conf_name: str = lmp_conf_name,
         output_lmp_tmpl_name: str = lmp_input_name,
         output_plm_tmpl_name: Optional[str] = None,
+        strict_revisions: bool = False,
     ) -> None:
         r"""Set lammps task.
 
@@ -99,11 +100,14 @@ def set_lmp(
             Generated lmp input file name.
         output_plm_tmpl_name : str
             Generated plm input file name.
+        strict_revisions : bool
+            Whether undefined V_* revision tokens fail task generation.
 
         """
         self.numb_models = numb_models
         self.lmp_template = Path(input_lmp_tmpl_name).read_text().split("\n")
         self.revisions = revisions
+        self.strict_revisions = strict_revisions
         self.traj_freq = traj_freq
         self.has_plm = input_plm_tmpl_name is not None
         self.do_custom = (
@@ -218,6 +222,7 @@ def _make_customized_task_group(
                             self.output_plm_tmpl_name if self.has_plm else None,
                             revisions=self.revisions,
                             traj_freq=self.traj_freq,
+                            strict_revisions=self.strict_revisions,
                         )
                         conf_fc = Path(self.output_lmp_conf_name).read_text()
                         lmp_tgroup.set_conf(

dpgen2/exploration/task/lmp_template_task_group.py

@@ -1,11 +1,18 @@
 import itertools
 import random
+import re
+import warnings
 from pathlib import (
     Path,
 )
 from typing import (
     List,
     Optional,
+    Set,
+)
+
+from dflow.python import (
+    FatalError,
 )
 
 from dpgen2.constants import (
@@ -49,9 +56,11 @@ def set_lmp(
         extra_pair_style_args: str = "",
         pimd_bead: Optional[str] = None,
         input_extra_files: Optional[List[str]] = None,
+        strict_revisions: bool = False,
     ) -> None:
         self.lmp_template = Path(lmp_template_fname).read_text().split("\n")
         self.revisions = revisions
+        self.strict_revisions = strict_revisions
         self.traj_freq = traj_freq
         self.extra_pair_style_args = extra_pair_style_args
         self.pimd_bead = pimd_bead
@@ -101,6 +110,21 @@ def make_task(
         if self.plm_set:
             templates.append(self.plm_template)
         conts = self.make_cont(templates, self.revisions)
+        # Validate: check for unreplaced V_* variables in substituted templates
+        template_raw = "\n".join(lmp_template)
+        if self.plm_set:
+            template_raw += "\n" + "\n".join(self.plm_template)
+        # Flatten all template variants (LAMMPS + PLUMED) for validation
+        all_conts = [c for c_list in conts for c in c_list]
+        try:
+            check_revisions_completeness(
+                all_conts,
+                list(self.revisions.keys()),
+                template_raw=template_raw,
+                strict=self.strict_revisions,
+            )
+        except ValueError as exc:
+            raise FatalError(str(exc)) from exc
         nconts = len(conts[0])
         for cc, ii in itertools.product(confs, range(nconts)):  # type: ignore
             if not self.plm_set:
@@ -214,7 +238,167 @@ def revise_lmp_input_plm(lmp_lines, in_plm, out_plm="output.plumed"):
 
 
 def revise_by_keys(lmp_lines, keys, values):
+    """Replace complete revision tokens without matching identifier prefixes."""
     for kk, vv in zip(keys, values):  # type: ignore
+        replacement = str(vv)
+        pattern = re.compile(rf"(?<![A-Za-z0-9_]){re.escape(kk)}(?![A-Za-z0-9_])")
         for ii in range(len(lmp_lines)):
-            lmp_lines[ii] = lmp_lines[ii].replace(kk, str(vv))
+            lmp_lines[ii] = pattern.sub(lambda _match: replacement, lmp_lines[ii])
     return lmp_lines
+
+
+# DPGEN and DPGEN2 templates conventionally use standalone V_* tokens for
+# revisions. Native LAMMPS or PLUMED identifiers may use the same spelling;
+# strict_revisions controls whether unexpected tokens are errors or warnings.
+_REVISION_VARIABLE_PATTERN = re.compile(
+    r"(?<![A-Za-z0-9_])V_[A-Z][A-Z0-9_]*(?![A-Za-z0-9_])"
+)
+
+
+def _strip_lammps_comments(content: str) -> str:
+    """Remove unquoted LAMMPS comments while preserving quoted hash characters.
+
+    This prevents V_* patterns in comments (e.g., "# set V_PRESS later")
+    from being flagged as unreplaced variables without hiding executable
+    placeholders inside single- or double-quoted strings.
+    """
+    stripped: List[str] = []
+    for line in content.split("\n"):
+        quote: Optional[str] = None
+        escaped = False
+        kept: List[str] = []
+        for char in line:
+            if escaped:
+                kept.append(char)
+                escaped = False
+            elif char == "\\" and quote is not None:
+                kept.append(char)
+                escaped = True
+            elif char in ("'", '"'):
+                if quote == char:
+                    quote = None
+                elif quote is None:
+                    quote = char
+                kept.append(char)
+            elif char == "#" and quote is None:
+                break
+            else:
+                kept.append(char)
+        stripped.append("".join(kept))
+    return "\n".join(stripped)
+
+
+def find_unreplaced_variables(content: str) -> Set[str]:
+    """Scan text for standalone V_* tokens that may be unreplaced revisions.
+
+    Strips LAMMPS comments before scanning to avoid false positives from
+    commented-out variable references.
+
+    Parameters
+    ----------
+    content : str
+        The LAMMPS input content after revision substitution.
+
+    Returns
+    -------
+    Set[str]
+        Set of variable names (e.g. {"V_PRESS", "V_UNDEFINED"}) still present.
+    """
+    stripped = _strip_lammps_comments(content)
+    return set(_REVISION_VARIABLE_PATTERN.findall(stripped))
+
+
+def report_undefined_revision_variables(
+    variables: Set[str],
+    revision_keys: List[str],
+    strict: bool,
+) -> None:
+    """Raise for undefined tokens in strict mode, otherwise emit a warning."""
+    if not variables:
+        return
+    message = (
+        f"LAMMPS template contains undefined revision variable(s): "
+        f"{sorted(variables)}. Defined revisions: {sorted(revision_keys)}. "
+        f"Please add missing variables to 'revisions' in your exploration config, "
+        f"or remove them from the template."
+    )
+    if strict:
+        raise ValueError(message)
+    warnings.warn(
+        message + " Continuing because strict revision validation is disabled.",
+        stacklevel=3,
+    )
+
+
+def check_revisions_completeness(
+    templates_content: List[str],
+    revision_keys: List[str],
+    template_raw: str = "",
+    strict: bool = True,
+) -> None:
+    """Validate that all V_* placeholders in the template have been substituted.
+
+    This function performs three checks:
+    1. **Raw-template definition check**: Compare complete placeholder tokens with
+       the revision keys before applying substitutions.
+    2. **Post-substitution residual check**: After applying revisions, scan the output
+       for any remaining V_* variables that were not replaced. This catches typos in
+       template variables or missing keys in revisions.
+    3. **Unused key warning**: If a revision key is defined but never appears in the
+       raw template, emit a warning (possible typo in the key name).
+
+    Parameters
+    ----------
+    templates_content : List[str]
+        List of template strings after revision substitution (one per revision combo).
+    revision_keys : List[str]
+        The keys defined in the revisions dict.
+    template_raw : str
+        The raw template content before substitution (for unused key detection).
+    strict : bool
+        If true, undefined V_* tokens are errors. If false, warn and continue
+        so templates may use V_* as native LAMMPS or PLUMED identifiers.
+
+    Raises
+    ------
+    ValueError
+        If undefined V_* tokens are found and strict is true.
+
+    Warns
+    -----
+    UserWarning
+        If undefined V_* tokens are found and strict is false, or if a
+        revision key is unused.
+    """
+    revision_key_set = set(revision_keys)
+
+    # Check 1: Compare raw tokens before substitution so a shorter defined key
+    # cannot erase the prefix of a longer undefined placeholder.
+    raw_variables = find_unreplaced_variables(template_raw) if template_raw else set()
+    undefined_raw = raw_variables - revision_key_set
+    report_undefined_revision_variables(
+        undefined_raw,
+        revision_keys,
+        strict=strict,
+    )
+
+    # Check 2: Residual unreplaced variables
+    all_unreplaced: Set[str] = set()
+    for content in templates_content:
+        all_unreplaced.update(find_unreplaced_variables(content))
+
+    report_undefined_revision_variables(
+        all_unreplaced - undefined_raw,
+        revision_keys,
+        strict=strict,
+    )
+
+    # Check 3: Unused revision keys (warning only)
+    if template_raw and revision_keys:
+        for key in revision_keys:
+            if key not in raw_variables:
+                warnings.warn(
+                    f"Revision key '{key}' is defined but does not appear in the "
+                    f"LAMMPS/PLUMED template. Possible typo?",
+                    stacklevel=3,
+                )

dpgen2/exploration/task/make_task_group_from_config.py

@@ -133,6 +133,11 @@ def lmp_template_task_group_args():
     doc_lmp_template_fname = "The file name of lammps input template"
     doc_plm_template_fname = "The file name of plumed input template"
     doc_revisions = "The revisions. Should be a dict providing the key - list of desired values pair. Key is the word to be replaced in the templates, and it may appear in both the lammps and plumed input templates. All values in the value list will be enmerated."
+    doc_strict_revisions = (
+        "Whether undefined V_* revision tokens fail task generation. "
+        "Defaults to false so templates using V_* as native LAMMPS or PLUMED "
+        "identifiers are warned about and preserved."
+    )
     doc_traj_freq = "The frequency of dumping configurations and thermodynamic states"
     doc_extra_pair_style_args = "The extra arguments for pair_style"
     doc_pimd_bead = "Bead index for PIMD, None for non-PIMD"
@@ -165,6 +170,13 @@ def lmp_template_task_group_args():
             alias=["plm_template", "plm"],
         ),
         Argument("revisions", dict, optional=True, default={}, doc=doc_revisions),
+        Argument(
+            "strict_revisions",
+            bool,
+            optional=True,
+            default=False,
+            doc=doc_strict_revisions,
+        ),
         Argument(
             "traj_freq",
             int,
@@ -201,6 +213,11 @@ def customized_lmp_template_task_group_args():
     doc_input_lmp_tmpl_name = "The file name of lammps input template"
     doc_input_plm_tmpl_name = "The file name of plumed input template"
     doc_revisions = "The revisions. Should be a dict providing the key - list of desired values pair. Key is the word to be replaced in the templates, and it may appear in both the lammps and plumed input templates. All values in the value list will be enmerated."
+    doc_strict_revisions = (
+        "Whether undefined V_* revision tokens fail task generation. "
+        "Defaults to false for customized templates so generated V_* tokens "
+        "are warned about and preserved."
+    )
     doc_traj_freq = "The frequency of dumping configurations and thermodynamic states"
     doc_custom_shell_commands = (
         "Customized shell commands to be run for each configuration. "
@@ -237,6 +254,13 @@ def customized_lmp_template_task_group_args():
             "custom_shell_commands", list, optional=False, doc=doc_custom_shell_commands
         ),
         Argument("revisions", dict, optional=True, default={}, doc=doc_revisions),
+        Argument(
+            "strict_revisions",
+            bool,
+            optional=True,
+            default=False,
+            doc=doc_strict_revisions,
+        ),
         Argument(
             "traj_freq",
             int,

tests/exploration/test_customized_lmp_templ_task_group.py

@@ -12,6 +12,9 @@
 )
 
 import numpy as np
+from dflow.python import (
+    FatalError,
+)
 
 try:
     from exploration.context import (
@@ -259,3 +262,47 @@ def test_lmp(self):
             * len(self.lmp_rev_mat["V_TEMP"])
             * 2,
         )
+
+    def test_empty_revisions_default_to_non_strict(self):
+        task_group = CustomizedLmpTemplateTaskGroup()
+        task_group.set_conf(self.confs)
+        task_group.set_lmp(
+            self.numb_models,
+            custom_shell_commands=self.shell_cmd,
+            revisions=self.rev_empty,
+            traj_freq=self.traj_freq,
+            input_lmp_conf_name="foo.lmp",
+            input_lmp_tmpl_name=self.lmp_template_fname,
+            input_plm_tmpl_name=None,
+            input_extra_files=[self.py_script],
+            output_dir_pattern="task_*",
+            output_lmp_conf_name="bar.lmp",
+            output_lmp_tmpl_name="lmp.template",
+        )
+
+        with self.assertWarnsRegex(UserWarning, "V_NSTEPS"):
+            task_group.make_task()
+
+        self.assertFalse(task_group.strict_revisions)
+        self.assertEqual(len(task_group), len(self.confs) * 2)
+
+    def test_empty_revisions_can_opt_into_strict_mode(self):
+        task_group = CustomizedLmpTemplateTaskGroup()
+        task_group.set_conf(self.confs)
+        task_group.set_lmp(
+            self.numb_models,
+            custom_shell_commands=self.shell_cmd,
+            revisions=self.rev_empty,
+            traj_freq=self.traj_freq,
+            input_lmp_conf_name="foo.lmp",
+            input_lmp_tmpl_name=self.lmp_template_fname,
+            input_plm_tmpl_name=None,
+            input_extra_files=[self.py_script],
+            output_dir_pattern="task_*",
+            output_lmp_conf_name="bar.lmp",
+            output_lmp_tmpl_name="lmp.template",
+            strict_revisions=True,
+        )
+
+        with self.assertRaisesRegex(FatalError, "V_NSTEPS"):
+            task_group.make_task()