Merge pull request #17 from zhaiwenxi/dpa-adapt-resolve-pretrained-all-strategies

Update dpa-adapt docs and CLI naming

Author: zhaiwenxi

doc/dpa_adapt/README.md

@@ -39,7 +39,7 @@ model.fit(train_data="/data/train", target_key="homo")
 model = DPAFineTuner(
     pretrained="DPA-3.1-3M", strategy="frozen_head", property_name="homo"
 )
-model.fit(train_data="/data/train", valid_data="/data/valid", target_key="homo")
+model.fit(train_data="/data/train", valid_data="/data/valid")
 
 # mft — downstream property head + auxiliary force-field head jointly
 model = DPAFineTuner(
@@ -53,41 +53,98 @@ model.fit(train_data="/data/qm9", aux_data="/data/spice2")
 
 ## Data preparation
 
-Your data must be in `deepmd/npy` format. `auto_convert` detects the input format automatically:
+DPA-ADAPT trains on `deepmd/npy` data. Use `dpa-adapt data convert` (or the Python
+`auto_convert` helper) to route common inputs into the right conversion pipeline:
+
+- **SMILES CSV**: a `.csv` file with a `SMILES`/`smiles` column. RDKit generates 3D
+  conformers, or existing `.mol`/`.sdf`/`.xyz`/`.pdb` files can be supplied with
+  `mol_dir`.
+- **Formula CSV + POSCAR template**: pass `fmt="formula"` and `poscar=...` to create
+  doped structures by random substitution on the host-element sublattice.
+- **Structure files / trajectories**: POSCAR, OUTCAR, `*.xyz`, `vasprun.xml`, ABACUS,
+  CP2K, Gaussian, LAMMPS, ASE, `deepmd/raw`, `deepmd/npy`, LMDB, and other dpdata
+  formats. Omit `fmt` when dpdata can infer it; set `fmt` explicitly for ambiguous
+  inputs.
 
 ```python
 from dpa_adapt import auto_convert
 
-# Structure file → dpdata (POSCAR, OUTCAR, extxyz, cif, …)
+# Structure file / trajectory → dpdata → deepmd/npy
 auto_convert("POSCAR", "./npy")
-auto_convert("calcs/**/OUTCAR", "./npy", fmt="vasp/outcar")  # glob → batch
+auto_convert("OUTCAR", "./npy", fmt="vasp/outcar")
+auto_convert("traj.extxyz", "./npy", fmt="extxyz")
+
+# Glob patterns: one match is converted as one system; multiple matches are batched.
+auto_convert("calcs/**/OUTCAR", "./npy_root", fmt="vasp/outcar")
+
+# CSV with a SMILES column → RDKit 3D conformers → deepmd/npy.
+# property_col names the input target column and output label name.
+auto_convert(
+    "molecules.csv",
+    "./npy",
+    fmt="smiles",          # optional when a SMILES/smiles column is present
+    smiles_col="SMILES",
+    property_col="HOMO",
+    train_ratio=0.9,
+)
 
-# CSV with SMILES column → RDKit 3D conformers → deepmd/npy
-auto_convert("data.csv", "./npy", property_name="homo", property_col="HOMO")
+# CSV + pre-generated molecular structures: skip RDKit conformer generation.
+auto_convert(
+    "molecules.csv",
+    "./npy",
+    fmt="smiles",
+    smiles_col="SMILES",
+    property_col="GAP",
+    mol_dir="./mol_files",
+    mol_template="id{row}.sdf",
+)
 
-# Composition formula CSV + template POSCAR → random atomic substitution → deepmd/npy
-# CSV: two columns, formula and property value (header optional)
-# e.g.  Ni0.65Gd0.15Fe0.10Co0.05Yb0.05O2H1    291.9
+# Composition formula CSV + template POSCAR → random atomic substitution → deepmd/npy.
+# CSV: header required; defaults are formula_col="formula" and property_col="Property".
+# e.g.  formula,Property
+#       Ni0.65Gd0.15Fe0.10Co0.05Yb0.05O2H1,291.9
 auto_convert(
     "compositions.csv",
     "./npy",
     fmt="formula",
     poscar="template.POSCAR",
-    property_name="overpotential",
-    sets=3,  # random doped structures per composition (default: 1)
+    formula_col="formula",
+    property_col="bandgap",
+    sets=3,        # random doped structures per composition row (default: 1)
+    seed=42,
 )
 ```
 
+CLI equivalents:
+
+```bash
+# SMILES table
+dpa-adapt data convert --input molecules.csv --output ./npy \
+  --fmt smiles --smiles-col SMILES --property-col HOMO --train-ratio 0.9
+
+# Formula table + POSCAR template
+dpa-adapt data convert --input compositions.csv --output ./npy --fmt formula \
+  --poscar template.POSCAR --formula-col formula --property-col bandgap --sets 3
+
+# Structure file or glob of calculation outputs
+dpa-adapt data convert --input POSCAR --output ./npy
+dpa-adapt data convert --input "calcs/**/OUTCAR" --output ./npy_root --fmt vasp/outcar
+```
+
 Lower-level helpers:
 
 ```python
-from dpa_adapt import convert, attach_labels, check_data
+from dpa_adapt import convert, batch_convert, attach_labels, check_data
 
-convert("calcs/**/OUTCAR", "./npy", fmt="vasp/outcar")
+convert("OUTCAR", "./npy", fmt="vasp/outcar")
+batch_convert("calcs/**/OUTCAR", "./npy_root", fmt="vasp/outcar")
 attach_labels(system, head="bandgap", values=np.array([1.0, 2.0, 3.0]))
 check_data("/data/system")  # → list[Issue]
 ```
 
+For the full option list and supported dpdata formats, see
+[`input_formats.md`](input_formats.md).
+
 ### Context features (fparam)
 
 fparam lets you condition the model on system-level context such as temperature, pressure, or experimental conditions.
@@ -161,7 +218,7 @@ from dpa_adapt import (
     train_test_split,  # formula-grouped splitting
     auto_convert,  # format-sniffing data conversion
     smiles_to_npy,  # CSV+SMILES → deepmd/npy
-    formula_csv_to_npy,  # composition formula CSV + POSCAR → deepmd/npy
+    formula_to_npy,  # composition formula CSV + POSCAR → deepmd/npy
     convert,  # structure file → deepmd/npy
     batch_convert,  # glob-based batch conversion
     check_data,  # data sanity checks
@@ -196,10 +253,16 @@ X = extract_descriptors(
 
 ```bash
 # Data conversion
+# Structure file
 dpa-adapt data convert --input POSCAR --output ./npy
-dpaad data convert --input data.csv --output ./npy --property-name homo
-dpa-adapt data convert --input comps.csv --output ./npy \
-  --fmt formula --poscar template.POSCAR --sets 3
+
+# SMILES CSV: --property-col names the input target column and output label name.
+dpaad data convert --input data.csv --output ./npy --fmt smiles \
+  --property-col homo
+
+# Formula CSV + POSCAR template
+dpa-adapt data convert --input comps.csv --output ./npy --fmt formula \
+  --poscar template.POSCAR --formula-col formula --property-col bandgap --sets 3
 
 # Fine-tune
 dpa-adapt fit --train-data ./npy/train --pretrained DPA-3.1-3M \
@@ -210,7 +273,7 @@ dpaad fit --train-data /data/qm9 --aux-data /data/spice2 \
   --pretrained /path/to/DPA-3.1-3M.pt --strategy mft --target-key homo
 
 # Predict / evaluate
-dpa-adapt predict --model model.pth --data ./npy/test
+dpa-adapt predict --model model.pth --data ./npy/test --output pred.npy
 dpa-adapt evaluate --model model.pth --data ./npy/test
 ```
 

dpa_adapt/_backend.py

@@ -41,15 +41,27 @@ def _is_url_or_name(path: str) -> bool:
 def resolve_pretrained_path(pretrained: str, cache_dir: str | None = None) -> str:
     """Resolve *pretrained* to a local file path, downloading if necessary.
 
-    If *pretrained* is a local path that exists, it is returned unchanged.
-    Otherwise it is treated as a built-in model name (e.g. ``"DPA-3.1-3M"``)
-    and resolved via :func:`deepmd.pretrained.download.resolve_model_path`.
+    If *pretrained* is a local checkpoint path, it is returned unchanged.  This
+    includes non-existing path-like values so callers can raise their own
+    context-specific ``not found`` errors or tests can monkeypatch checkpoint
+    loading.  Bare names (e.g. ``"DPA-3.1-3M"``) are resolved via
+    :func:`deepmd.pretrained.download.resolve_model_path`.
     """
     import os as _os
+    from pathlib import Path as _Path
 
     if _os.path.isfile(pretrained):
         return pretrained
 
+    p = _Path(pretrained)
+    is_path_like = (
+        p.is_absolute()
+        or any(sep and sep in pretrained for sep in (_os.sep, _os.altsep))
+        or p.suffix.lower() in {".pt", ".pth"}
+    )
+    if is_path_like:
+        return pretrained
+
     from deepmd.pretrained.download import resolve_model_path as _download
 
     path = _download(pretrained, cache_dir=cache_dir)

dpa_adapt/cli.py

@@ -1,13 +1,13 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
-"""CLI entry point for the ``dpa`` command.
+"""CLI entry point for the ``dpa-adapt`` and ``dpaad`` commands.
 
-Unlike the deepmd-kit ``dp`` command, ``dpa`` is a standalone CLI that
+Unlike the deepmd-kit ``dp`` command, ``dpa-adapt`` is a standalone CLI that
 focuses solely on DPA model fine-tuning, descriptor extraction,
 cross-validation, prediction, evaluation, and data preparation.
 
-``dpa --help`` does not load torch — the parser is pure argparse and the
-handlers (and the DPA stack) are imported lazily only when a subcommand
-actually runs.
+``dpa-adapt --help`` and ``dpaad --help`` do not load torch — the parser is
+pure argparse and the handlers (and the DPA stack) are imported lazily only
+when a subcommand actually runs.
 """
 
 from __future__ import (
@@ -287,6 +287,7 @@ def _cmd_data_convert(args: argparse.Namespace) -> int:
         formula_col=args.formula_col,
         base_element=args.base_element,
         sets=args.sets,
+        seed=args.seed,
         overwrite=args.overwrite,
         validate=args.validate,
         strict=args.strict,
@@ -376,12 +377,12 @@ def _cmd_data_attach_labels(args: argparse.Namespace) -> int:
 
 
 def get_parser() -> argparse.ArgumentParser:
-    """Build the standalone ``dpa`` argument parser.
+    """Build the standalone ``dpa-adapt`` / ``dpaad`` argument parser.
 
     Returns
     -------
     argparse.ArgumentParser
-        The fully configured parser for the ``dpa`` CLI.
+        The fully configured parser for the ``dpa-adapt`` / ``dpaad`` CLI.
     """
     try:
         from dpa_adapt import (
@@ -651,6 +652,9 @@ def get_parser() -> argparse.ArgumentParser:
     parser_data_convert.add_argument("--sets", type=int, default=1,
                                      help="Random structures per formula "
                                           "(fmt=formula, default: 1).")
+    parser_data_convert.add_argument("--seed", type=int, default=42,
+                                     help="Random seed for selecting substituted host-atom sites "
+                                          "(fmt=formula, default: 42).")
     parser_data_convert.add_argument("--overwrite", action="store_true")
 
     # data validate
@@ -682,7 +686,7 @@ def get_parser() -> argparse.ArgumentParser:
 
 
 def main(args: Sequence[str] | None = None) -> None:
-    """Entry point for the ``dpa`` CLI.
+    """Entry point for the ``dpa-adapt`` / ``dpaad`` CLI.
 
     Parameters
     ----------
@@ -712,7 +716,7 @@ def main(args: Sequence[str] | None = None) -> None:
         else:
             handler = _DISPATCH.get(parsed_args.command)
             if handler is None:
-                print(f"Unknown dpa command: {parsed_args.command}", file=sys.stderr)
+                print(f"Unknown dpa-adapt command: {parsed_args.command}", file=sys.stderr)
                 sys.exit(1)
             sys.exit(handler(parsed_args))
     except Exception as exc:

dpa_adapt/data/__init__.py

@@ -2,7 +2,8 @@
 """Data loading, conversion, validation, and SMILES/type-map utilities.
 
 All public names are lazily imported so that ``import dpa_adapt.data``
-(and therefore ``dpa --help``) does not pull in dpdata, torch, or rdkit.
+(and therefore ``dpa-adapt --help`` / ``dpaad --help``) does not pull in
+dpdata, torch, or rdkit.
 """
 
 __all__ = [

dpa_adapt/main.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
-"""Entry point for the ``dpa`` CLI.
+"""Entry point for the ``dpa-adapt`` and ``dpaad`` CLIs.
 
 This is the console_script target registered in pyproject.toml.
 """

source/tests/dpa_adapt/test_cli_smoke.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
-"""Smoke tests for the standalone ``dpa`` CLI.
+"""Smoke tests for the standalone ``dpa-adapt`` / ``dpaad`` CLI.
 
 Test that all verbs are reachable, ``--help`` does not trigger eager loading
 of torch or any DPA implementation, and dispatch tables cover all verbs.
@@ -12,8 +12,8 @@
 import sys
 
 
-class TestDpaParserRegistration:
-    """Verify all dpa verbs are registered in the standalone parser."""
+class TestDpaAdaptParserRegistration:
+    """Verify all dpa-adapt verbs are registered in the standalone parser."""
 
     def test_dpa_verbs_registered(self):
         from dpa_adapt.cli import (
@@ -50,8 +50,8 @@ def test_data_subcommands_registered(self):
             assert expected in data_verbs, f"{expected!r} missing from {data_verbs}"
 
 
-class TestDpaHelpNoTorch:
-    """``dpa --help`` must NOT trigger a torch import."""
+class TestDpaAdaptHelpNoTorch:
+    """``dpa-adapt --help`` must NOT trigger a torch import."""
 
     def test_help_does_not_load_torch(self):
         from unittest.mock import (
@@ -80,7 +80,7 @@ def test_help_does_not_load_torch(self):
 
         if not torch_already:
             assert "torch" not in sys.modules, (
-                "torch was loaded during dpa --help path!"
+                "torch was loaded during dpa-adapt --help path!"
             )