From f5a383c6b48ac08c7c4e21b44250d5078527cb3c Mon Sep 17 00:00:00 2001 From: njzjz-bot Date: Sun, 15 Mar 2026 04:21:05 +0000 Subject: [PATCH 1/3] docs(skills): add dpdata driver skill --- .gitignore | 4 + skills/dpdata-driver/SKILL.md | 144 ++++++++++++++++++++++++++++++++++ 2 files changed, 148 insertions(+) create mode 100644 skills/dpdata-driver/SKILL.md diff --git a/.gitignore b/.gitignore index 7fd27471..645b6210 100644 --- a/.gitignore +++ b/.gitignore @@ -34,3 +34,7 @@ tests/data_*.h5 tests/data_*/ tests/tmp.* tests/.coverage + +# local dev artifact +uv.lock +.venv/ diff --git a/skills/dpdata-driver/SKILL.md b/skills/dpdata-driver/SKILL.md new file mode 100644 index 00000000..9cdb2452 --- /dev/null +++ b/skills/dpdata-driver/SKILL.md @@ -0,0 +1,144 @@ +--- +name: dpdata-driver +description: Use dpdata Python Driver plugins to label systems (energies/forces/virials) via System.predict(), list available drivers, and build Driver objects (ase/deepmd/gaussian/sqm/hybrid). Use when working with dpdata Python API (not CLI) and you need driver-based energy/force prediction, plugin registration keys, or examples of using dpdata with ASE calculators or DeePMD models. +--- + +# dpdata-driver + +Use dpdata “driver plugins” to **label** a `dpdata.System` (predict energies/forces/virials) and obtain a `dpdata.LabeledSystem`. + +## Key idea + +- A **Driver** converts an unlabeled `System` into a `LabeledSystem` by computing: + - `energies` (required) + - `forces` (optional but common) + - `virials` (optional) + +In dpdata, this is exposed as: + +- `System.predict(*args, driver="dp", **kwargs) -> LabeledSystem` + +`driver` can be: + +- a **string key** (plugin name), e.g. `"ase"`, `"dp"`, `"gaussian"` +- a **Driver object**, e.g. `Driver.get_driver("ase")(...)` + +## List supported driver keys (runtime) + +When unsure what drivers exist in *this* dpdata version/env, query them at runtime: + +```python +from dpdata.driver import Driver + +print(sorted(Driver.get_drivers().keys())) +``` + +In the current repo state, keys include: + +- `ase` +- `dp` / `deepmd` / `deepmd-kit` +- `gaussian` +- `sqm` +- `hybrid` + +(Exact set depends on dpdata version and installed extras.) + +## Minimal workflow + +```python +import dpdata +from dpdata.system import System + +sys = System("input.xyz", fmt="xyz") +ls = sys.predict(driver="ase", calculator=...) # returns dpdata.LabeledSystem +``` + +### Verify you got a labeled system + +```python +assert "energies" in ls.data +# optional: +# assert "forces" in ls.data +# assert "virials" in ls.data +``` + +## Example: use the ASE driver with an ASE calculator (runnable) + +This is the easiest *fully runnable* example because it doesn’t require external QM software. + +Dependencies (recommended): declare script dependencies with uv inline metadata, then run with `uv run`. + +```python +# /// script +# requires-python = ">=3.12" +# dependencies = [ +# "dpdata", +# "numpy", +# "ase", +# ] +# /// +``` + +Script: + +```python +import numpy as np +from ase.calculators.emt import EMT +from dpdata.system import System + +# write a tiny molecule +open("tmp.xyz", "w").write("""2\n\nH 0 0 0\nH 0 0 0.74\n""") + +sys = System("tmp.xyz", fmt="xyz") +ls = sys.predict(driver="ase", calculator=EMT()) + +print("energies", np.array(ls.data["energies"])) +print("forces shape", np.array(ls.data["forces"]).shape) +if "virials" in ls.data: + print("virials shape", np.array(ls.data["virials"]).shape) +else: + print("virials: ") +``` + +## Example: pass a Driver object instead of a string + +```python +from ase.calculators.emt import EMT +from dpdata.driver import Driver +from dpdata.system import System + +sys = System("tmp.xyz", fmt="xyz") +ase_driver = Driver.get_driver("ase")(calculator=EMT()) +ls = sys.predict(driver=ase_driver) +``` + +## Hybrid driver + +Use `driver="hybrid"` to sum energies/forces/virials from multiple drivers. + +The `HybridDriver` accepts `drivers=[ ... ]` where each item is either: + +- a `Driver` instance +- a dict like `{"type": "sqm", ...}` (type is the driver key) + +Example (structure only; may require external executables): + +```python +from dpdata.driver import Driver + +hyb = Driver.get_driver("hybrid")( + drivers=[ + {"type": "sqm", "qm_theory": "DFTB3"}, + {"type": "dp", "dp": "frozen_model.pb"}, + ] +) +# ls = sys.predict(driver=hyb) +``` + +## Notes / gotchas + +- Many drivers require extra dependencies or external programs: + - `dp` requires `deepmd-kit` + a model file + - `gaussian` requires Gaussian and a valid executable (default `g16`) + - `sqm` requires AmberTools `sqm` +- If you just need file format conversion, use the existing **dpdata CLI** skill instead. From 1607cc69681b7ed6d0948c385fbc88a3f9d263af Mon Sep 17 00:00:00 2001 From: njzjz-bot Date: Mon, 23 Mar 2026 07:02:33 +0000 Subject: [PATCH 2/3] docs(dpdata-driver): address AI review comments Load built-in plugins before listing driver keys, align the uv example with the project's Python support floor, and use a safer/runnable ASE example with Lennard-Jones and pathlib-based file writes. Authored by OpenClaw (model: gpt-5.4) --- skills/dpdata-driver/SKILL.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/skills/dpdata-driver/SKILL.md b/skills/dpdata-driver/SKILL.md index 9cdb2452..e5c6d48b 100644 --- a/skills/dpdata-driver/SKILL.md +++ b/skills/dpdata-driver/SKILL.md @@ -28,11 +28,14 @@ In dpdata, this is exposed as: When unsure what drivers exist in *this* dpdata version/env, query them at runtime: ```python +import dpdata from dpdata.driver import Driver print(sorted(Driver.get_drivers().keys())) ``` +`import dpdata` ensures built-in plugins are loaded before listing registered drivers. + In the current repo state, keys include: - `ase` @@ -70,7 +73,7 @@ Dependencies (recommended): declare script dependencies with uv inline metadata, ```python # /// script -# requires-python = ">=3.12" +# requires-python = ">=3.8" # dependencies = [ # "dpdata", # "numpy", @@ -82,15 +85,17 @@ Dependencies (recommended): declare script dependencies with uv inline metadata, Script: ```python +from pathlib import Path + import numpy as np -from ase.calculators.emt import EMT +from ase.calculators.lj import LennardJones from dpdata.system import System # write a tiny molecule -open("tmp.xyz", "w").write("""2\n\nH 0 0 0\nH 0 0 0.74\n""") +Path("tmp.xyz").write_text("""2\n\nH 0 0 0\nH 0 0 0.74\n""") sys = System("tmp.xyz", fmt="xyz") -ls = sys.predict(driver="ase", calculator=EMT()) +ls = sys.predict(driver="ase", calculator=LennardJones()) print("energies", np.array(ls.data["energies"])) print("forces shape", np.array(ls.data["forces"]).shape) @@ -103,12 +108,12 @@ else: ## Example: pass a Driver object instead of a string ```python -from ase.calculators.emt import EMT +from ase.calculators.lj import LennardJones from dpdata.driver import Driver from dpdata.system import System sys = System("tmp.xyz", fmt="xyz") -ase_driver = Driver.get_driver("ase")(calculator=EMT()) +ase_driver = Driver.get_driver("ase")(calculator=LennardJones()) ls = sys.predict(driver=ase_driver) ``` From 76f7970cadafef0e5dd272dcc1cbf064cdfd7a40 Mon Sep 17 00:00:00 2001 From: Jinzhe Zeng Date: Mon, 23 Mar 2026 17:45:35 +0800 Subject: [PATCH 3/3] Update SKILL.md with additional metadata Added license, compatibility, and metadata information. Signed-off-by: Jinzhe Zeng --- skills/dpdata-driver/SKILL.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/skills/dpdata-driver/SKILL.md b/skills/dpdata-driver/SKILL.md index e5c6d48b..680bf373 100644 --- a/skills/dpdata-driver/SKILL.md +++ b/skills/dpdata-driver/SKILL.md @@ -1,6 +1,11 @@ --- name: dpdata-driver description: Use dpdata Python Driver plugins to label systems (energies/forces/virials) via System.predict(), list available drivers, and build Driver objects (ase/deepmd/gaussian/sqm/hybrid). Use when working with dpdata Python API (not CLI) and you need driver-based energy/force prediction, plugin registration keys, or examples of using dpdata with ASE calculators or DeePMD models. +license: LGPL-3.0-or-later +compatibility: Requires dpdata or uv for running dpdata +metadata: + author: njzjz-bot + version: '1.0' --- # dpdata-driver