Skip to content

Commit 04b3ba4

Browse files
docs(skills): add dpdata minimizer skill (#955)
This PR adds an Agent Skill under `skills/` documenting dpdata minimizer plugins and `System.minimize()` usage. Includes a runnable ASE minimization example and clarifies the driver/minimizer relationship (ASEMinimizer expects a dpdata Driver, not a raw ASE calculator). Authored by OpenClaw (model: gpt-5.2) <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added new documentation for geometry minimization using dpdata minimizer plugins. * Documented the System.minimize API with supported minimizers. * Included practical usage examples and important configuration notes for optimal results. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: njzjz-bot <njzjz-bot@users.noreply.github.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
1 parent 61126fe commit 04b3ba4

File tree

1 file changed

+86
-0
lines changed

1 file changed

+86
-0
lines changed

skills/dpdata-minimizer/SKILL.md

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
name: dpdata-minimizer
3+
description: Minimize geometries with dpdata minimizer plugins via System.minimize(), including how minimizers relate to drivers (ASEMinimizer needs a dpdata Driver) and how to list supported minimizers (ase/sqm). Use when doing geometry optimization/minimization through dpdata Python API.
4+
---
5+
6+
# dpdata-minimizer
7+
8+
Use dpdata “minimizer plugins” to **optimize/minimize geometry** and return a `dpdata.LabeledSystem`.
9+
10+
## Key idea
11+
12+
- A **Minimizer** performs geometry optimization (updates coordinates) and returns labeled results.
13+
- dpdata exposes this as:
14+
15+
```python
16+
System.minimize(*args, minimizer: str|Minimizer, **kwargs) -> LabeledSystem
17+
```
18+
19+
## List supported minimizer keys (runtime)
20+
21+
```python
22+
from dpdata.driver import Minimizer
23+
24+
print(sorted(Minimizer.get_minimizers().keys()))
25+
```
26+
27+
In the current dpdata repo, minimizer keys include:
28+
29+
- `ase`
30+
- `sqm`
31+
32+
## Relationship to drivers (important)
33+
34+
Some minimizers require a **dpdata Driver object**.
35+
36+
Example: `ASEMinimizer` takes a dpdata `Driver` in its constructor:
37+
38+
- `minimizer="ase"` requires `driver=<dpdata Driver>` (e.g. the ASE driver wrapping an ASE calculator).
39+
40+
So you generally do:
41+
42+
1. Construct a driver
43+
1. Construct a minimizer (or let dpdata do it by passing the right kwargs)
44+
1. Call `System.minimize(...)`
45+
46+
## Runnable example: ASE minimizer with an ASE calculator
47+
48+
Use uv inline script metadata so the example runs reproducibly with `uv run`.
49+
50+
```python
51+
# /// script
52+
# requires-python = ">=3.12"
53+
# dependencies = [
54+
# "dpdata",
55+
# "numpy",
56+
# "ase",
57+
# ]
58+
# ///
59+
60+
import numpy as np
61+
from ase.calculators.emt import EMT
62+
63+
from dpdata.driver import Driver
64+
from dpdata.system import System
65+
66+
open("tmp.xyz", "w").write("""2\n\nH 0 0 0\nH 0 0 0.74\n""")
67+
68+
sys = System("tmp.xyz", fmt="xyz")
69+
70+
# Build a dpdata driver that can provide energies/forces to ASE optimizers.
71+
ase_driver = Driver.get_driver("ase")(calculator=EMT())
72+
73+
# Minimize using the ASE minimizer plugin.
74+
# NOTE: ASEMinimizer expects `driver` (not `calculator`) as input.
75+
ls = sys.minimize(minimizer="ase", driver=ase_driver, fmax=0.05, max_steps=5)
76+
77+
print("coords", np.array(ls.data["coords"]).shape)
78+
print("energies", np.array(ls.data["energies"]))
79+
print("forces", np.array(ls.data["forces"]).shape)
80+
```
81+
82+
## Notes / gotchas
83+
84+
- `System.minimize(...)` accepts either a minimizer key string or a Minimizer object.
85+
- If you previously used `System.predict(driver="ase", calculator=...)`, be aware that minimization is different: you need to pass a **driver** into the minimizer (ASEMinimizer does not accept `calculator=`).
86+
- `sqm` minimizer requires AmberTools `sqm` executable and typically won’t be runnable in CI.

0 commit comments

Comments
 (0)