add DPA-ADAPT toolkit for downstream property adaptation

[zhaiwenxi]

Summary

This PR adds DPA-ADAPT, a toolkit for adapting pretrained DPA models to downstream atomistic property prediction tasks.

The new package provides a scikit-learn-style Python API and standalone CLI for fine-tuning, descriptor extraction, prediction, evaluation, cross-validation, and data preparation, without requiring users to manually write DeePMD-kit training input files.

Main changes

• Add the top-level dpa_adapt Python package.
• Add standalone CLI entry points:
  • dpa-adapt
  • dpaad
• Support multiple adaptation strategies:
  • frozen_sklearn: frozen DPA descriptors with scikit-learn regressors
  • frozen_head: train a property head on top of a frozen DPA backbone
  • finetune: end-to-end DPA fine-tuning
  • mft: multi-task fine-tuning with auxiliary energy/force training
• Add data utilities for:
  • DeepMD/npy loading and validation
  • label attachment
  • descriptor caching
  • train/test split and cross-validation
  • SMILES/formula-based conversion workflows
  • optional frame parameters via fparam.npy
• Add prediction and evaluation helpers with MAE, RMSE, and R2 reporting.
• Add documentation under doc/dpa_adapt/.
• Add a runnable QM9 HOMO-LUMO gap example under examples/dpa_adapt/.
• Add dpa-adapt optional dependencies in pyproject.toml.
• Add dedicated lightweight CI for source/tests/dpa_adapt/.

Co-authored-by: zirenjin <zirenjin@umich.edu>

Summary by CodeRabbit

• New Features
  • Added the DPA-ADAPT toolkit with a new command-line interface for data conversion, validation, training, prediction, evaluation, and descriptor extraction.
  • Introduced support for multiple adaptation workflows, including frozen-sklearn, frozen-head, fine-tuning, and multi-task training.
  • Added data handling for SMILES, formulas, structures, label attachment, and condition features.
  • Included a new example workflow and expanded user documentation for setup and usage.

[iProzd]

Others LGTM.

[njzjz-bot]

Thanks for the large DPA-ADAPT contribution. I found several correctness / integration issues that should be fixed before merge, so I’m requesting changes.

1. DPA-ADAPT tests require scikit-learn, but the test extra does not install it.

   The new tests live under source/tests/dpa_adapt, so they are included by the normal pytest source/tests paths. Some of them import DPA-ADAPT modules that import sklearn at module import time (source/tests/dpa_adapt/test_split_cv.py → dpa_adapt/cv.py). The CPU workflow currently masks this by manually adding scikit-learn, but other test paths do not: CUDA installs .[gpu,test,lmp,cu12,torch,jax] and runs python -m pytest source/tests, and the default tox env installs only test,cpu. Those will fail with ModuleNotFoundError: sklearn unless the dependency is added to the appropriate test/CI extras or the optional tests skip cleanly. Prefer installing/testing the advertised dpa-adapt extra in CI so the package metadata is validated too.

2. The descriptor cache key can return stale descriptors for changed systems.

   dpa_adapt/data/desc_cache.py builds _system_fingerprint() from metadata plus only the first/last 64 flattened entries of coords and cells. Any change in the middle of a larger trajectory/system keeps the same cache key, so both the aggregate cache and per-system cache can reuse descriptors from a different structure. Since these descriptors directly drive fitting and prediction, the cache identity needs to cover the full relevant array contents (for example a streaming hash over all arrays, or a robust hash of all set.*/*.npy inputs) before this is safe.

3. Unsupported training elements are silently ignored in type-map resolution.

   In dpa_adapt/finetuner.py, _resolve_type_maps() catches every ValueError from both read_data_type_map_union() and validate_type_map_subset(). That means a real validation failure such as data containing an element not covered by the checkpoint is swallowed as if it were merely the “no atom_names” case, and training proceeds with an incompatible checkpoint type map. Please split the try block so only the missing-atom-names case is ignored, and unsupported-element validation errors propagate clearly.

4. MFT rejects valid raw-index data without type_map.raw.

   read_data_type_map_union() treats dpdata placeholder names such as Type_0/Type_1 as real elements. MFT then validates those against the checkpoint type map and fails, although the surrounding code comments say data without atom_names should be allowed to use raw atom indices. This is inconsistent with finetuner._read_data_type_map(), which explicitly filters all-Type_* placeholder maps. Please make the shared type-map reader ignore all-placeholder maps, or reuse the same filtering logic before subset validation.

5. load_dataset() does not use the direct custom-label fallback used elsewhere.

   dpa_adapt/data/dataset.py only checks resolved_key in system.data. Custom labels such as property.npy, homo.npy, or bandgap.npy under set.*/ are not generally loaded into dpdata.System.data; _load_labels() in finetuner.py already has a direct set.*/{key}.npy fallback for this. Since the CV CLI calls load_dataset(args.data, label_key=...), valid datasets with these custom label files can be skipped as missing. Please share/reuse the same label-discovery semantics here.

A smaller consistency issue: DPAFineTuner.__init__ should validate fparam_dim the same way DPATrainer and MFTFineTuner do. Currently the default frozen_sklearn path accepts fparam_dim=-1 and silently treats it as disabled.

I verified the code locations against PR head c47834c83d54b8e372bc2119474f4a944a5618f7 and ran python3 -m compileall -q dpa_adapt successfully. I could not run the new pytest suite in this local checkout because pytest/numpy/dpdata/sklearn/torch are not installed in the available environment.

— OpenClaw 2026.6.8 (model: custom-chat-jinzhezeng-group/gpt-5.5)