Skip to content

Commit 14a71f1

Browse files
OutisLiOutisLi
authored
docs: recommend DPA4 and DPA4C in README (#5979)
## Summary - Recommend DPA4 when accuracy is the priority and DPA4C when throughput or system scale is the binding constraint. - Update the pretrained and fine-tuning quick start to use a built-in DPA4 OMat24 single-task checkpoint, and remove the experimental DPA4-only LoRA workflow from the project landing page. - Replace the DPA-3 and DeepPot-SE default examples with DPA4 and DPA4C examples, and refresh both Pareto figures from the latest results. ## Validation - All pre-commit hooks passed during commit. - `git diff --check upstream/master...HEAD` - `dp pretrained download -h` lists the documented DPA4 checkpoint. - Verified the DPA4, DPA4C, and DPA4 OMat24 links return HTTP 200. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Updated the README to feature DPA4 and DPA4C as the primary model families. - Refreshed pretrained-model and fine-tuning guidance with DPA4 OMat24 checkpoints. - Added training examples for accuracy-focused DPA4 and throughput-focused DPA4C workflows. - Removed outdated LoRA and legacy branch-selection instructions. - Updated references and links for DPA4, DPA4 OMat24, and DPA4C. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
1 parent bdb4007 commit 14a71f1

3 files changed

Lines changed: 76 additions & 56 deletions

File tree

‎README.md‎

Lines changed: 76 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,9 @@ and deploy it at simulation scale.**
2020

2121
> [!IMPORTANT]
2222
> **A pretrained model can be your starting point, not just your end result.**
23-
> Download a built-in DPA checkpoint, fine-tune the full model, or use a
24-
> [DPA-4 LoRA adapter][dpa4-lora] with PyTorch single-task training, then test,
25-
> export, and deploy it through the same DeePMD-kit workflow.
23+
> Download a built-in pretrained DPA4 checkpoint, fine-tune the full model for
24+
> your system, then test, export, and deploy it through the same DeePMD-kit
25+
> workflow.
2626
2727
DeePMD-kit turns quantum-mechanical reference data into fast, scalable
2828
interatomic potentials. Use it across molecular and materials science—from
@@ -38,16 +38,16 @@ dynamics.
3838

3939
## ⚡ Why DeePMD-kit
4040

41-
| | Advantage | What it unlocks |
42-
| --- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
43-
| 🧬 | **Pretrained-first workflows** | Download [pretrained DPA models][pretrained], fine-tune full models, use [DPA-4 LoRA adapters][dpa4-lora] with PyTorch single-task training, or adapt learned representations to downstream properties with [DPA-ADAPT]. |
44-
| 🏗️ | **Training from scratch** | Design a model for a new system or physical target, then train it with single-task, multi-task, and distributed workflows across supported backends. |
45-
| 🧠 | **Modern model portfolio** | Start with efficient DeepPot-SE descriptors or move to [DPA][model-guide] for large atomistic models. |
46-
| 🧲 | **More than energy and force** | Model virials, Hessians, spin and magnetic forces, dipoles, polarizabilities, electronic density of states, atomic populations, and arbitrary intensive or extensive properties. |
47-
| 🔄 | **Backend flexibility** | Train or run supported models with [TensorFlow, PyTorch, JAX, or Paddle][backends], with backend-aware model formats and conversion paths for compatible architectures. |
48-
| 🚀 | **Performance from training to MD** | Use CPUs, CUDA GPUs, ROCm source builds, distributed training, model compression, compiled DPA-4 paths, AOTInductor `.pt2` export, and MPI-enabled simulation. |
49-
| 🔌 | **Deploy where science happens** | Use the CLI, Python, C, C++, or Node.js, then connect models to LAMMPS, i-PI, ASE, GROMACS, JAX MD, nvalchemi, OpenMM, Amber, CP2K, ABACUS, and more. |
50-
| 🧩 | **Open and extensible** | Compose hybrid potentials, add analytical ZBL or long-range corrections, create custom models and operators, or connect external GNNs such as MACE and NequIP through plugins. |
41+
| | Advantage | What it unlocks |
42+
| --- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
43+
| 🧬 | **Pretrained-first workflows** | Download [pretrained DPA4 models][dpa4-omat24], fine-tune full models, or adapt supported pretrained representations to downstream properties with [DPA-ADAPT]. |
44+
| 🏗️ | **Training from scratch** | Design a model for a new system or physical target, then train it with single-task, multi-task, and distributed workflows across supported backends. |
45+
| 🧠 | **Modern model portfolio** | For conservative energy/force interatomic potentials, start with [DPA4] for accuracy or [DPA4C] for simulation throughput and scale. |
46+
| 🧲 | **More than energy and force** | Model virials, Hessians, spin and magnetic forces, dipoles, polarizabilities, electronic density of states, atomic populations, and arbitrary intensive or extensive properties. |
47+
| 🔄 | **Backend flexibility** | Train or run supported models with [TensorFlow, PyTorch, JAX, or Paddle][backends], with backend-aware model formats and conversion paths for compatible architectures. |
48+
| 🚀 | **Performance from training to MD** | Use CPUs, CUDA GPUs, ROCm source builds, distributed training, compiled DPA4 paths, compressed DPA4C CUDA inference, AOTInductor `.pt2` export, and MPI-enabled simulation. |
49+
| 🔌 | **Deploy where science happens** | Use the CLI, Python, C, C++, or Node.js, then connect models to LAMMPS, i-PI, ASE, GROMACS, JAX MD, nvalchemi, OpenMM, Amber, CP2K, ABACUS, and more. |
50+
| 🧩 | **Open and extensible** | Compose hybrid potentials, add analytical ZBL or long-range corrections, create custom models and operators, or connect external GNNs such as MACE and NequIP through plugins. |
5151

5252
> [!TIP]
5353
> On supported descriptors and workloads, [model compression][compression] can
@@ -62,7 +62,7 @@ feature page.
6262

6363
```mermaid
6464
flowchart LR
65-
A["Pretrained DPA model"] --> C["Fine-tune on target data"]
65+
A["Pretrained DPA4 model"] --> C["Fine-tune on target data"]
6666
B["Model configuration"] --> D["Train from scratch"]
6767
E["Target reference data"] --> C
6868
E --> D
@@ -72,14 +72,13 @@ flowchart LR
7272
F --> H["Molecular dynamics"]
7373
```
7474

75-
1. **Choose a starting point:** download a pretrained DPA checkpoint for
76-
adaptation, or configure a model to train from scratch.
75+
1. **Choose a starting point:** download a pretrained DPA4 checkpoint for
76+
adaptation, or configure DPA4 or DPA4C to train from scratch.
7777
1. **Prepare target data** in DeePMD's NumPy format or convert structures and
7878
trajectories with [dpdata][data].
79-
1. **Fine-tune or train:** adapt the full pretrained model, use
80-
[DPA-4 LoRA adapters][dpa4-lora] with PyTorch single-task training, or
81-
optimize a new model with single-task, multi-task, and distributed training
82-
workflows.
79+
1. **Fine-tune or train:** adapt the full pretrained DPA4 model, or optimize a
80+
new DPA4 or DPA4C model with single-task, multi-task, and distributed
81+
training workflows.
8382
1. **Validate and export** with [`dp test`][testing], [`dp freeze`][freeze],
8483
backend conversion, embedding extraction, and supported compression paths.
8584
1. **Run simulation** through Python or native APIs, or load the model into a
@@ -98,31 +97,38 @@ dp -h
9897
The [installation guide][installation] covers pip, conda-forge, containers,
9998
offline packages, GPU builds, LAMMPS, i-PI, and source installation.
10099

101-
### Fine-tune from a pretrained DPA model
100+
### Fine-tune a pretrained DPA4 model
102101

103-
Download a built-in checkpoint, inspect its branches, and fine-tune the branch
104-
that matches your target system:
102+
Download a built-in checkpoint, start from its matching released training
103+
configuration, and fine-tune it on your target data. This example uses DPA4-Neo,
104+
one of the recommended general-purpose sizes:
105105

106106
```bash
107-
dp pretrained download DPA-3.2-5M
108-
dp --pt show ~/.cache/deepmd/pretrained/models/DPA-3.2-5M.pt model-branch
109-
dp --pt train input.json \
110-
--finetune ~/.cache/deepmd/pretrained/models/DPA-3.2-5M.pt \
111-
--model-branch <branch> \
112-
--use-pretrain-script
107+
dp pretrained download DPA4-Neo-OMat24-v20260805
108+
curl -fsSL \
109+
https://huggingface.co/deepmodelingcommunity/DPA4-OMat24/resolve/main/DPA4-Neo-OMat24-v20260805.json \
110+
-o input_finetune.json
113111
```
114112

115-
`DPA-3.2-5M` is a PyTorch multi-task checkpoint: run the trainer in PyTorch
116-
mode with `dp --pt` and select the branch that matches your system with
117-
`--model-branch` (list them with
118-
`dp --pt show ~/.cache/deepmd/pretrained/models/DPA-3.2-5M.pt model-branch`). The
119-
`--use-pretrain-script` option imports that branch's descriptor and fitting
120-
configuration, so `input.json` does not need to reproduce the DPA-3.2
121-
architecture.
122-
123-
The [fine-tuning guide][finetune] covers full-model adaptation. [DPA-4 LoRA
124-
fine-tuning][dpa4-lora] is available for PyTorch single-task training.
125-
[DPA-ADAPT] reuses pretrained DPA representations for downstream
113+
The [DPA4 OMat24 release][dpa4-omat24] provides Nano, Mini, Neo, Air, and Plus
114+
checkpoints together with their matching training configurations. The downloaded
115+
`input_finetune.json` matches the Neo checkpoint above; for another size or
116+
version, use the correspondingly named JSON file. Keep its complete `model`
117+
section unchanged, including the full-periodic-table `type_map`; replace the
118+
training and validation data, and use a smaller learning rate for fine-tuning.
119+
Then run:
120+
121+
```bash
122+
dp --pt train input_finetune.json \
123+
--finetune ~/.cache/deepmd/pretrained/models/DPA4-Neo-OMat24-v20260805.pt
124+
```
125+
126+
These are PyTorch single-task checkpoints, so no model branch selection is
127+
needed. They target inorganic materials in the OMat24 chemical space; validate
128+
accuracy before using them outside that domain.
129+
130+
The [fine-tuning guide][finetune] covers full-model adaptation. [DPA-ADAPT]
131+
reuses supported pretrained DPA representations for downstream
126132
property-prediction tasks.
127133

128134
Pretrained model names can also be resolved and cached automatically by
@@ -131,7 +137,7 @@ Python:
131137
```python
132138
from deepmd.infer import DeepPot
133139

134-
potential = DeepPot("DPA-3.2-5M")
140+
potential = DeepPot("DPA4-Neo-OMat24-v20260805")
135141
```
136142

137143
### Train a model from scratch
@@ -142,37 +148,49 @@ checkpoint. Clone the examples and start with the compact water system:
142148

143149
```bash
144150
git clone https://github.com/deepmodeling/deepmd-kit.git
145-
cd deepmd-kit/examples/water/se_e2_a
151+
cd deepmd-kit/examples/water/dpa4
146152

147-
# TensorFlow backend
148-
dp train input.json
153+
# Accuracy-first DPA4 model
154+
dp --pt train input.json
149155

150-
# Or PyTorch
151-
dp --pt train input_torch.json
156+
# Or the throughput-first DPA4C model
157+
cd ../dpa4c
158+
dp --pt-expt train input.json
152159
```
153160

154161
Ready-to-run inputs include:
155162

156-
- [DPA-3 water training](./examples/water/dpa3/input_torch.json)
157-
- [DPA-4 water training](./examples/water/dpa4/input.json)
158-
- [Multi-task training](./examples/water_multi_task/pytorch_example/input_torch.json)
163+
- [DPA4 water training](./examples/water/dpa4/input.json)
164+
- [DPA4C high-throughput water training](./examples/water/dpa4c/input.json)
165+
- [DPA4 multi-task training](./examples/water/dpa4/input_multitask.json)
159166
- [DPA-ADAPT property prediction](./examples/dpa_adapt/README.md)
160167

161168
For a guided end-to-end example, open the [web quick-start notebook][quick-start].
162169

163170
## 🧠 Choose a model family
164171

165-
DeepPot-SE is a strong default: efficient, established, and broadly supported.
166-
For large atomistic models, start with [DPA-4](https://docs.deepmodeling.com/projects/deepmd/en/latest/model/dpa4.html).
172+
For conservative energy/force interatomic potentials, start with the DPA4
173+
family. The choice between its two primary models follows the constraint that
174+
matters most for your workload:
175+
176+
| Priority | Start with | Why |
177+
| ---------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------- |
178+
| Highest accuracy | [DPA4] | SO(3)-equivariant message passing targets the accuracy frontier. |
179+
| Highest throughput or system scale | [DPA4C] | A compact one-hop descriptor targets the throughput frontier and supports compressed CUDA inference. |
180+
181+
DPA4 uses the PyTorch backend (`dp --pt`). DPA4C currently uses the PyTorch
182+
Exportable backend (`dp --pt-expt`); its compressed CUDA path requires
183+
`float32`.
167184

168-
Use the [model guide][model-guide] to compare model families, supported backends,
169-
targets, data formats, precision, compression, and deployment constraints.
185+
For other physical targets, use the [model guide][model-guide] to select a
186+
compatible model and backend. The guide also compares data formats, precision,
187+
compression, and deployment constraints.
170188

171189
<p align="center">
172-
<img alt="DPA4 energy and force accuracy versus saturated throughput" src="./doc/_static/dpa4-performance.webp" width="1200">
190+
<img alt="DPA4 and DPA4C energy and force accuracy versus saturated throughput" src="./doc/_static/dpa4-performance.webp" width="1200">
173191
</p>
174192

175-
<p align="center"><em>DPA4 provides a family of accuracy–throughput trade-offs for different deployment budgets.</em></p>
193+
<p align="center"><em>For energy/force potentials, DPA4 and DPA4C span accuracy–throughput trade-offs for different deployment budgets.</em></p>
176194

177195
## 🔬 Go beyond conventional force fields
178196

@@ -258,7 +276,9 @@ DeePMD-kit is licensed under the
258276
[data]: https://docs.deepmodeling.com/projects/deepmd/en/latest/data/dpdata.html
259277
[documentation]: https://docs.deepmodeling.com/projects/deepmd/en/latest/
260278
[dpa-adapt]: https://docs.deepmodeling.com/projects/deepmd/en/latest/dpa_adapt/overview.html
261-
[dpa4-lora]: https://docs.deepmodeling.com/projects/deepmd/en/latest/model/dpa4.html#lora-fine-tuning
279+
[dpa4]: https://docs.deepmodeling.com/projects/deepmd/en/latest/model/dpa4.html
280+
[dpa4-omat24]: https://huggingface.co/deepmodelingcommunity/DPA4-OMat24
281+
[dpa4c]: https://docs.deepmodeling.com/projects/deepmd/en/latest/model/dpa4c.html
262282
[embeddings]: https://docs.deepmodeling.com/projects/deepmd/en/latest/inference/embedding.html
263283
[finetune]: https://docs.deepmodeling.com/projects/deepmd/en/latest/train/finetuning.html
264284
[freeze]: https://docs.deepmodeling.com/projects/deepmd/en/latest/freeze/freeze.html

‎doc/_static/dpa4-cps-throughput.webp‎

45.4 KB
Loading

‎doc/_static/dpa4-performance.webp‎

-24.6 KB
Loading

0 commit comments

Comments
 (0)