feat(skills): add DPA-4c distillation workflow by Fillianore · Pull Request #227 · AI4MS/MatCreator

Fillianore · 2026-08-13T11:48:53Z

Add concept-level and deepmd-skill support for distilling a DPA-4c student model from a fine-tuned DPA-4 teacher:

mlff concept SKILL: rewrite the distillation procedure into explicit Phase A (teacher NPT MD) -> Phase B (teacher inference labeling) -> Phase C (student training + two-level evaluation), with strict phase ordering gates and seed/training-set provenance checks.
deepmd SKILL + supported models reference: document DPA-4c CLI usage (--pt-expt, never --finetune due to OOM for sel=[999999]), the --skip-neighbor-stat requirement, and the recommended Bohrium image (dpa4-mlip-340e01f9) on a 5090 GPU.
deepmd_prepare.py: fix epoch-key alias handling so exactly one epoch key remains in the training dict (avoids dargs strict-schema failure).
references/dpa4c_distill_input.json: verified input template from a completed 1M-step DPA-4c distillation run.

Add concept-level and deepmd-skill support for distilling a DPA-4c student model from a fine-tuned DPA-4 teacher: - mlff concept SKILL: rewrite the distillation procedure into explicit Phase A (teacher NPT MD) -> Phase B (teacher inference labeling) -> Phase C (student training + two-level evaluation), with strict phase ordering gates and seed/training-set provenance checks. - deepmd SKILL + supported models reference: document DPA-4c CLI usage (--pt-expt, never --finetune due to OOM for sel=[999999]), the --skip-neighbor-stat requirement, and the recommended Bohrium image (dpa4-mlip-340e01f9) on a 5090 GPU. - deepmd_prepare.py: fix epoch-key alias handling so exactly one epoch key remains in the training dict (avoids dargs strict-schema failure). - references/dpa4c_distill_input.json: verified input template from a completed 1M-step DPA-4c distillation run.

qchempku2017 · 2026-08-13T12:58:53Z

+
+## Recommended Procedure — Generate a force field via distillation
+
+> **Strict phase ordering — Phase A → Phase B → Phase C.**


Maybe better call each step "stages" instead of "phases" in case LLM confuse stages in pipeline with crystalline phases.

qchempku2017 · 2026-08-13T13:01:35Z

+>
+> **If you believe a phase can be skipped or shortened for your particular structure,
+> that belief is precisely the error this rule exists to prevent.** Skipping Phase A
+> (teacher MD) or Phase B (proper labeling) and jumping straight to Phase C (student


Not precise enough. Maybe say: "Skipping generating and labeling new samples by running MD with teacher model is not allowed. Specifically, do not simply relabel existing DFT structures with the teacher model and use these structures in training the student model, as xxx."

qchempku2017 · 2026-08-13T13:02:05Z

+A valid **teacher model** must satisfy BOTH conditions:
+
+1. It is a **fine-tuned** model on the target system, i.e., it has already gone through the
+   fine-tuning procedure above on DFT-labeled data of that system.


Add "DO NOT use pretrained models"

qchempku2017 · 2026-08-13T13:03:02Z

+
+1. It is a **fine-tuned** model on the target system, i.e., it has already gone through the
+   fine-tuning procedure above on DFT-labeled data of that system.
+2. It is a **single-task** model (dedicated to the target system).


For a model that supports multi-task training (such as DPA-3), a teacher model must be a single task model specifically fine-tuned in the target system.

qchempku2017 · 2026-08-13T13:04:05Z

-  DFT-labeled test set from the corresponding fine-tuning workflow. If that is not available, then
-  consider choosing an appropriate subset of the distillation testing set and re-compute them with DFT
-  (subset number of frames times number of atoms in each frame should not exceed 10000 total atoms).
+The distillation workflow mirrors the fine-tuning workflow phase by phase, except that the labels are


Distillation contents are quite long. Maybe separate "fine-tuning.md" and a "distillation.md" from the main concept skill?

qchempku2017 · 2026-08-13T13:05:11Z

+  exactly as in fine-tuning Phase A.
+
+The only systematic difference is the sampling scale: because the student is trained from scratch,
+distillation needs roughly **20 times** the number of frames used in fine-tuning.


Much more. Maybe change to 50 times at least. Distillation won't cost much.

qchempku2017 · 2026-08-13T13:05:52Z

+> **(1) NPT ensemble** — mandatory for strain diversity; never switch to NVT/NVE without
+> explicit user approval. **(2) Entropy-based structure selection** — mandatory after
+> MD sampling and before labeling. **(3) ~100× frame scale** — distillation needs
+> roughly 100× the frames of fine-tuning (≥ 20000 for simple systems).


100x conflicts with 20x mentioned before.

qchempku2017 · 2026-08-13T13:06:36Z

+
+### Phase B — Teacher inference labeling (replaces DFT)
+
+Label the entropy-selected structures by **teacher model inference** (single-point energy, force and


By inferencing with the teacher model to obtain xxx, xxx, xxx

qchempku2017 · 2026-08-13T13:08:34Z

+> 2. The total labeled frame count is **≥ ~20000** (simple systems) / **≥ ~40000**
+>    (complex systems) / **≥ ~100000** (very complex systems), consistent with the
+>    Phase A output recommendation above.
+> 3. The frames span a **diverse configuration space** (different cell shapes, strains,


Different cell shapes may cause confusion. Do you mean that all structures may be sampled from the same supercell matrix while allowing lattice vectors to vary during NPT sampling? Or you must have different supercell matrices?

qchempku2017 · 2026-08-13T13:09:40Z

+   all teacher-labeled frames.
+
+2. Train the DPA-4c student model **from scratch** (no pretrained initialization). Because the student
+   starts from scratch, training is much longer than fine-tuning: use about **1,000,000 (1M) training


Stop instructing agent with traning steps. Now that num_epochs keyword is supported, always let the agent use num_epochs.

Use 1000 epochs, if possible.

qchempku2017 · 2026-08-13T13:11:31Z

 5.  Also, do not use nvidia GPUs older than V100 as they no longer support the triton AOT induction route of
    modern pytorch, which is compulsory for deepmd-kit>=3.2.0.
+
+## DPA-4c distillation student (dpa4c descriptor)


DPA-4c ("dpa4c" descriptor, only used as student models during distillation)

qchempku2017 · 2026-08-13T13:12:52Z

+dp --pt-expt train input.json --init-model <pretrain.pt> --skip-neighbor-stat
+```
+
+- `--finetune` is **prohibited** for DPA-4c: its bias-adjustment dense forward pass


--finetune keyword is prohibited for DPA-4c. Always use only dp --pt-expt train input.json --skip-neighbor-stat to train from scratch.

qchempku2017 · 2026-08-13T13:14:02Z

+architecture** (dpa2, dpa3, dpa4/SeZM, se_atten_v2, ...).
+
+**[For bohrium submission] Image and machine:** recommended image
+`registry.dp.tech/dptech/dpa-calculator:dpa4-mlip-340e01f9` on a **5090** GPU machine.


I recommend just add a table of models and their correponding images in the previous machine section

By the way, are 5090 nodes available now? Are they no longer busy? Why L20_48g nodes cannot be used?

qchempku2017 · 2026-08-13T13:15:39Z


+---
+
+# DPA-4c distillation (student model training)


Maybe no need to duplicate here as you have already mentioned in supported_deepmd_models.md

qchempku2017

Good work overall, but I have a few suggestions.

ruoyuwang1995nya · 2026-08-14T06:46:53Z

@Fillianore Maybe you can check the suggestion first?

…#227) Concept skill split (qchempku2017): - Extract the fine-tuning and distillation procedures from the main concept SKILL.md into references/fine-tuning.md and references/distillation.md. SKILL.md now stays a concise overview that points to the two reference files (365 -> 97 lines). Wording & correctness fixes per review: - Rename "Phase" -> "Stage" throughout (avoid confusion with crystalline phases). - Distillation: strengthen the seed-vs-training-set rule to explicitly forbid relabeling existing DFT structures with the teacher. - Distillation Stage Zero gate: "DO NOT use pretrained models"; clarify that multi-task-capable models (e.g. DPA-3) must be single-task fine-tuned on the target system to qualify as a teacher. - Unify the distillation frame multiplier to ~100x (was inconsistent 20x/100x). - Stage B: rephrase labeling as "inferencing with the teacher model to obtain energy, forces and virial". - Clarify the configuration-diversity check (NPT lattice-vector fluctuation on the same supercell), and classify systems whose initial structures span multiple distinct cell types as complex. - Use ~1000 epochs (num_epochs keyword) instead of training steps. deepmd skill: - Remove the duplicated DPA-4c distillation block from SKILL.md; keep a short pointer to supported_deepmd_models.md. Keep the --init-model flag; make the --finetune prohibition wording stricter. - supported_deepmd_models.md: rename the DPA-4c section heading.

…pochs) - distillation.md: 1000 epochs -> 50 epochs. - dpa4c_distill_input.json: replace numb_steps=1000000 with num_epochs=50, consistent with the num_epochs keyword recommended since deepmd 3.2.0.

Fillianore requested review from qchempku2017 and ruoyuwang1995nya August 13, 2026 11:48

qchempku2017 reviewed Aug 13, 2026

View reviewed changes

Fillianore added 2 commits August 14, 2026 14:50

chore(skills): unify distillation training length to 50 epochs (num_e…

73a1900

…pochs) - distillation.md: 1000 epochs -> 50 epochs. - dpa4c_distill_input.json: replace numb_steps=1000000 with num_epochs=50, consistent with the num_epochs keyword recommended since deepmd 3.2.0.

Fillianore merged commit 10088de into AI4MS:devel Aug 14, 2026


		## Recommended Procedure — Generate a force field via distillation

		> Strict phase ordering — Phase A → Phase B → Phase C.


		### Phase B — Teacher inference labeling (replaces DFT)

		Label the entropy-selected structures by teacher model inference (single-point energy, force and

Uh oh!

Conversation

Fillianore commented Aug 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

DPA-4c ("dpa4c" descriptor, only used as student models during distillation)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qchempku2017 Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qchempku2017 left a comment

Choose a reason for hiding this comment

Uh oh!

ruoyuwang1995nya commented Aug 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

qchempku2017 Aug 13, 2026 •

edited

Loading