Merge branch 'master' into pr/dpa4

Author: wanghan-iapcm

.pre-commit-config.yaml

@@ -30,7 +30,7 @@ repos:
         exclude: ^source/3rdparty
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.15.15
+    rev: v0.15.16
     hooks:
       - id: ruff
         args: ["--fix"]

deepmd/loggers/training.py

@@ -38,6 +38,7 @@ def format_training_message(
     wall_time: float,
     eta: int | None = None,
     current_time: datetime.datetime | None = None,
+    step_time: float | None = None,
 ) -> str:
     """Format the summary message for one training interval.
 
@@ -52,13 +53,18 @@ def format_training_message(
     current_time : datetime.datetime | None, optional
         Current local time used to estimate the finish timestamp. This is only
         used when ``eta`` is provided.
+    step_time : float | None, optional
+        Average wall-clock time per training step over this interval, in
+        seconds. Shown only when provided.
 
     Returns
     -------
     str
         The formatted training message.
     """
     msg = f"Batch {batch:7d}: total wall time = {wall_time:.2f} s"
+    if step_time is not None:
+        msg += f", avg = {step_time:.4f} s/step"
     if isinstance(eta, int):
         eta_seconds = int(eta)
         msg += (

deepmd/pt_expt/train/training.py

@@ -1452,6 +1452,7 @@ def run(self) -> None:
         self.wrapper.train()
         wall_start = time.time()
         last_log_time = wall_start
+        last_log_step = self.start_step
 
         for step_id in range(self.start_step, self.num_steps):
             cur_lr = float(self.lr_schedule.value(step_id))
@@ -1465,9 +1466,6 @@ def run(self) -> None:
                 )
                 task_key = self.model_keys[model_index]
 
-            if self.timing_in_training:
-                t_start = time.time()
-
             # --- forward / backward ---
             self.optimizer.zero_grad(set_to_none=True)
             input_dict, label_dict = self.get_data(is_train=True, task_key=task_key)
@@ -1488,9 +1486,6 @@ def run(self) -> None:
 
             self._optimizer_step()
 
-            if self.timing_in_training:
-                t_end = time.time()
-
             # --- display ---
             display_step_id = step_id + 1
             if self.display_in_training and (
@@ -1598,9 +1593,14 @@ def _to_float(v: Any) -> float:
                     current_time = time.time()
                     wall_elapsed = current_time - wall_start
                     interval_wall_time = current_time - last_log_time
+                    # average wall time per step over the interval since the
+                    # last log (number of steps counted exactly once across
+                    # intervals via last_log_step)
+                    interval_steps = max(1, display_step_id - last_log_step)
+                    step_time = interval_wall_time / interval_steps
                     last_log_time = current_time
+                    last_log_step = display_step_id
                     if self.timing_in_training:
-                        step_time = t_end - t_start
                         steps_completed_since_restart = max(
                             1,
                             display_step_id - self.start_step,
@@ -1619,9 +1619,9 @@ def _to_float(v: Any) -> float:
                                     current_time,
                                     tz=datetime.timezone.utc,
                                 ).astimezone(),
+                                step_time=step_time,
                             )
                         )
-                        log.info("step=%d  step_time=%.4fs", display_step_id, step_time)
                     else:
                         log.info(
                             format_training_message(

doc/agent-skills.md

@@ -0,0 +1,82 @@
+# Agent Skills
+
+DeePMD-kit provides official [Agent Skills](https://agentskills.io/what-are-skills) that help AI agents run
+DeePMD-kit workflows in a reproducible way. These skills capture
+project-specific operating knowledge—such as training inputs, model
+deployment, LAMMPS integration, and Python inference patterns—so an agent can
+turn a high-level request into concrete files, commands, and validation steps.
+
+The DeePMD-kit skills were initially developed in the
+[Computational Chemistry Agent Skills](https://github.com/jinzhezenggroup/computational-chemistry-agent-skills)
+project as part of the work described below. They are now maintained directly
+in the DeePMD-kit repository under `skills/`.
+
+## List of skills
+
+- `deepmd-train-dpa3`: Train DeePMD-kit models with the DPA3 descriptor and the
+  PyTorch backend, including input generation, neighbor-selection choices,
+  training, freezing, and testing.
+- `deepmd-finetune-dpa3`: Fine-tune DPA3 models from self-trained checkpoints,
+  multi-task pretrained models, or built-in models downloaded by `dp pretrained download`.
+- `deepmd-train-se-e2-a`: Train classical Deep Potential models with the
+  `se_e2_a` descriptor, including preparation of training JSON files and
+  post-training validation.
+- `deepmd-python-inference`: Run Python and CLI inference with trained or
+  frozen DeePMD-kit models, including energy, force, virial, descriptor, and
+  model-deviation workflows.
+- `lammps-deepmd`: Prepare, explain, and run LAMMPS simulations with DeePMD-kit
+  potentials, including common NVE, NVT, and NPT setups.
+
+## Related reference
+
+The DeePMD-kit skills were originally developed as part of the following
+paper:
+
+- Mingwei Ding, Chen Huang, Yibo Hu, Yifan Li, Zitian Lu, Xingtai Yu, Duo
+  Zhang, Wenxi Zhai, Tong Zhu, Qiangqiang Gu, and Jinzhe Zeng. [Automating
+  Computational Chemistry Workflows via OpenClaw and Domain-Specific
+  Skills](https://doi.org/10.1021/acs.jctc.6c00622). *Journal
+  of Chemical Theory and Computation*, 2026.
+
+## Install skills
+
+### If you are a user
+
+The easiest way is to send this page to your agent and ask it to install the
+skills for you. Users usually do not need to perform manual installation.
+
+### If you are an agent
+
+If you already have a DeePMD-kit checkout, run this command from the repository
+root:
+
+```bash
+npx -y skills add ./skills -a openclaw -y
+```
+
+If you do not have a checkout, the same skills can also be installed directly
+from GitHub:
+
+```bash
+npx -y skills add https://github.com/deepmodeling/deepmd-kit/tree/master/skills \
+    -a openclaw -y
+```
+
+The examples above require Node.js/npm so that `npx` is available, and they
+install the skills for OpenClaw. Replace `openclaw` with the target agent name
+when installing for another agent. The GitHub command lets the skill CLI fetch
+the repository for you. For large repositories or slow networks, this can take
+longer than installing from an existing local checkout. Refresh or restart the
+session afterward so the installed skills are reloaded.
+
+## Minimal verification
+
+Ask the agent to perform a small task that exercises the installed skill
+without launching an expensive calculation. For example:
+
+- “Use the `deepmd-python-inference` skill to write a minimal Python snippet
+  for loading a frozen DeePMD-kit model and evaluating one frame.”
+- “Use the `deepmd-train-dpa3` skill to draft a small DPA3 training input for a
+  water dataset, but do not start training.”
+- “Use the `lammps-deepmd` skill to prepare an NVT LAMMPS input file for a
+  DeePMD-kit model, and explain each command.”

doc/index.rst

@@ -45,6 +45,7 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r
    inference/index
    cli
    third-party/index
+   agent-skills
    nvnmd/index
    env
    troubleshooting/index

source/tests/pt_expt/test_training.py

@@ -8,6 +8,7 @@
 4. Loss decreases over those steps
 """
 
+import datetime
 import os
 import shutil
 import tempfile
@@ -18,6 +19,9 @@
 
 import torch
 
+from deepmd.loggers.training import (
+    format_training_message,
+)
 from deepmd.pt_expt.entrypoints.main import (
     get_trainer,
 )
@@ -1684,5 +1688,60 @@ def test_compiled_matches_eager_per_task(self) -> None:
             shutil.rmtree(tmpdir, ignore_errors=True)
 
 
+class TestFormatTrainingMessageStepTime(unittest.TestCase):
+    """The pt_expt trainer reports the average wall time per step over each
+    display interval by passing ``step_time`` to ``format_training_message``
+    (replacing the former standalone ``step=... step_time=...`` debug line).
+    These tests cover both branches of the optional ``step_time``/``eta``
+    arguments so the "avg = ... s/step" segment is rendered only when requested.
+    """
+
+    def test_without_step_time(self) -> None:
+        """``step_time=None`` (default) omits the step-time segment."""
+        msg = format_training_message(batch=100, wall_time=18.41)
+        self.assertEqual(msg, "Batch     100: total wall time = 18.41 s")
+        self.assertNotIn("s/step", msg)
+
+    def test_with_step_time(self) -> None:
+        """``step_time`` is rendered with 4 decimals after the wall time."""
+        msg = format_training_message(batch=100, wall_time=18.41, step_time=0.1841)
+        self.assertEqual(
+            msg,
+            "Batch     100: total wall time = 18.41 s, avg = 0.1841 s/step",
+        )
+
+    def test_step_time_zero_is_shown(self) -> None:
+        """A literal ``0.0`` step time is still shown (not treated as absent)."""
+        msg = format_training_message(batch=1, wall_time=0.5, step_time=0.0)
+        self.assertIn("avg = 0.0000 s/step", msg)
+
+    def test_with_step_time_and_eta(self) -> None:
+        """Step time appears before the eta segment."""
+        current_time = datetime.datetime(
+            2026, 6, 7, 5, 21, 29, tzinfo=datetime.timezone.utc
+        )
+        msg = format_training_message(
+            batch=100,
+            wall_time=18.41,
+            eta=100,
+            current_time=current_time,
+            step_time=0.1841,
+        )
+        self.assertIn("total wall time = 18.41 s, avg = 0.1841 s/step, eta = ", msg)
+        # ordering: wall time -> step time -> eta
+        self.assertLess(msg.index("s/step"), msg.index("eta ="))
+
+    def test_eta_without_step_time(self) -> None:
+        """Eta still works when no step time is supplied."""
+        current_time = datetime.datetime(
+            2026, 6, 7, 5, 21, 29, tzinfo=datetime.timezone.utc
+        )
+        msg = format_training_message(
+            batch=100, wall_time=18.41, eta=100, current_time=current_time
+        )
+        self.assertNotIn("s/step", msg)
+        self.assertIn("eta = ", msg)
+
+
 if __name__ == "__main__":
     unittest.main()

source/tests/pt_expt/utils/test_neighbor_list.py

@@ -476,7 +476,17 @@ def test_pt_expt_multiframe_equivalence(name: str) -> None:
 
 @pytest.mark.parametrize("name", list(ALL_MODELS))  # descriptor family
 def test_default_fallback(name: str) -> None:
-    """``neighbor_list=None`` equals an explicit DefaultNeighborList byte-for-byte."""
+    """``neighbor_list=None`` dispatches to the same DefaultNeighborList builder.
+
+    ``None`` and an explicit ``DefaultNeighborList()`` are the identical builder
+    (``call_common`` does ``builder = nl if nl is not None else DefaultNeighborList()``),
+    so the two forward passes are the *same computation*; on CPU they are
+    bit-identical.  We compare with a tight tolerance rather than exact equality
+    because the two passes are independent forward evaluations, and on CUDA the
+    GNN message-passing scatter (atomic adds) is not bit-reproducible run-to-run,
+    so the virial can differ by ~1 ULP between the passes (a real dispatch bug
+    would differ by orders of magnitude more).
+    """
     coord_np, atype_np, box_np = _system()
     md = get_model(copy.deepcopy(ALL_MODELS[name])).to(env.DEVICE)
     md.eval()
@@ -492,8 +502,10 @@ def test_default_fallback(name: str) -> None:
         ).requires_grad_(True)
         outs[tag] = md.forward(coord_t, atype_t, box=box_t, do_atomic_virial=True, **kw)
     for k in ("energy", "force", "virial"):
-        np.testing.assert_array_equal(
+        np.testing.assert_allclose(
             outs["none"][k].detach().cpu().numpy(),
             outs["explicit"][k].detach().cpu().numpy(),
+            rtol=1e-10,
+            atol=1e-12,
             err_msg=f"{name} {k}",
         )