Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,16 @@

## Unreleased

DPA checkpoint migration (#91):

- Added explicit trust-gated offline conversion of legacy DPA-SSE training
`.pt` checkpoints whose NumPy scalar metadata is rejected by DeePMD's
`weights_only=True` loader. The converter does not patch upstream or change
global deserialization policy; it preserves float64 tensors exactly, removes
optimizer data and records input/output SHA-256 in a separate provenance file.
Only use it with verified trusted checkpoints; model predictions still require
scientific reference validation.

NEP model-format compatibility (#90):

- Recognize GPUMD format-version-1 energy NEP files such as NEP89 (first
Expand Down
24 changes: 24 additions & 0 deletions docs/backends/dpa.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,30 @@ want as `--head` (`HEAD` in an INCAR file):
dp --pt show DPA-3.1-3M.pt model-branch
```

## Trusted training checkpoint compatibility

Some DPA-SSE training checkpoints include NumPy scalars in both optimizer
metadata and model training information. DeePMD explicitly uses
`torch.load(weights_only=True)`, so these checkpoints cannot be loaded
directly. For a **locally verified, trusted** source file only, convert it
without modifying the original:

```bash
.venv-dpa/bin/python scripts/convert_dpa_checkpoint.py \
models/SSE-VASP-dpa2.pt models/SSE-VASP-dpa2-inference.pt \
--i-trust-this-file
```

The converter runs unsafe pickle deserialization **only after explicit opt-in**;
never use it for a checkpoint from an unknown or untrusted source. It drops
optimizer state, normalizes NumPy scalars inside the model metadata and
verifies that every tensor, dtype and value is unchanged when reloaded with
`weights_only=True`. A separate `.conversion.json` preserves both SHA-256
hashes, conversions and the original source path. This verifies *file
compatibility*, not energy/force equivalence: run real DeePMD predictions with
the converted model and compare against the original trusted reference before
scientific use.

## Things to know

- **Leaving out the head on a multi-task checkpoint is a fatal configuration
Expand Down
20 changes: 20 additions & 0 deletions docs/backends/dpa.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,26 @@ DPA 模型通过 `deepmd-kit` 加载。很多 DPA 模型是多任务模型,带
dp --pt show DPA-3.1-3M.pt model-branch
```

## 可信训练 checkpoint 的兼容转换

部分 DPA-SSE 训练检查点在优化器状态和模型训练信息中包含 NumPy 标量。
DeePMD 明确使用 `torch.load(weights_only=True)`,因此无法直接读取。
**只有明确确认来源可信**时,才使用以下离线转换,原始文件不会被修改:

```bash
.venv-dpa/bin/python scripts/convert_dpa_checkpoint.py \
models/SSE-VASP-dpa2.pt models/SSE-VASP-dpa2-inference.pt \
--i-trust-this-file
```

转换脚本仅在显式授权后才执行可能运行任意代码的 pickle 反序列化,
不要用它处理不可信的模型文件。脚本会去掉优化器状态,把模型元数据中的
NumPy 标量转换为 Python 标量,并通过 `weights_only=True` 重新读取,
验证所有张量的名称、精度、形状和数值都没有变化。独立的
`.conversion.json` 记录原文件路径、两份 SHA-256 与转换项目。
这只能证明**文件兼容**,不能证明能量和力的预测等价;正式科研使用前,
仍需用真实 DeePMD 推理与可信参考结果进行对照。

## 需要知道的事

- **多任务模型必须写 head,否则报错。** 没有默认分支。
Expand Down
200 changes: 200 additions & 0 deletions scripts/convert_dpa_checkpoint.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,200 @@
"""Convert a TRUSTED DeepMD PyTorch training checkpoint for safe inference.

DeepMD 3.1.3 uses torch.load(weights_only=True) even for user-supplied .pt files.
Some training checkpoints contain numpy.float64 objects in _extra_state and
optimizer metadata, which PyTorch's restricted unpickler rejects.

This offline, explicit-opt-in utility removes the optimizer and converts only
NumPy scalar values in the model state to equivalent Python scalars. It NEVER
changes tensor values or dtype, and proves that the result loads with
weights_only=True. Untrusted pickle files MUST NOT be passed to this script.
"""

from __future__ import annotations

import argparse
import hashlib
import json
import os
import tempfile
from collections import OrderedDict
from pathlib import Path
from typing import Any


def _sha256(path: Path) -> str:
digest = hashlib.sha256()
with path.open("rb") as handle:
for block in iter(lambda: handle.read(1024 * 1024), b""):
digest.update(block)
return digest.hexdigest()


def _normalize(value: Any, *, torch: Any, numpy: Any, changes: list[str], path: str):
"""Keep tensor objects; replace numpy scalars without changing numeric values."""
if isinstance(value, torch.Tensor):
return value
if isinstance(value, numpy.generic):
normalized = value.item()
if not isinstance(normalized, int | float | bool | complex | str | bytes):
raise TypeError(f"Unsupported NumPy scalar at {path}: {type(value)!r}")
changes.append(f"{path}: {type(value).__name__} -> {type(normalized).__name__}")
return normalized
if value is None or isinstance(value, str | bytes | bool | int | float | complex):
return value
if isinstance(value, dict | OrderedDict):
if not all(isinstance(key, str | int) for key in value):
raise TypeError(f"Unsupported mapping key at {path}")
return type(value)(
(
key,
_normalize(
item,
torch=torch,
numpy=numpy,
changes=changes,
path=f"{path}.{key}",
),
)
for key, item in value.items()
)
if isinstance(value, list | tuple):
items = [
_normalize(
item, torch=torch, numpy=numpy, changes=changes, path=f"{path}[{index}]"
)
for index, item in enumerate(value)
]
return tuple(items) if isinstance(value, tuple) else items
raise TypeError(
f"Unsupported value in model state at {path}: {type(value)!r}; "
"refusing an implicit conversion"
)


def _tensors(value: Any, prefix: str = ""):
"""Visit all named tensor leaves, including nested model state."""
import torch # noqa: PLC0415

if isinstance(value, torch.Tensor):
yield prefix, value
elif isinstance(value, dict):
for name, child in value.items():
yield from _tensors(child, f"{prefix}.{name}")
elif isinstance(value, tuple | list):
for idx, child in enumerate(value):
yield from _tensors(child, f"{prefix}[{idx}]")


def convert_checkpoint(source: Path, target: Path, *, trusted: bool) -> dict[str, Any]:
"""Write a weights-only-compatible .pt and its separate provenance JSON.

Unsafe pickle unpickling is allowed ONLY when the caller passes trusted=True.
The original file is never modified; existing output files are refused.
"""
if not trusted:
raise PermissionError(
"Refusing unsafe checkpoint deserialization without explicit trust. "
"Only convert checkpoints from a verified trusted source."
)
if source.suffix.lower() != ".pt" or target.suffix.lower() != ".pt":
raise ValueError("Source and target must both have .pt extensions")
if not source.is_file():
raise FileNotFoundError(source)
if source.resolve() == target.resolve():
raise ValueError("Never overwrite the original DPA training checkpoint")
provenance_file = target.with_suffix(".conversion.json")
if target.exists() or provenance_file.exists():
raise FileExistsError("Refusing to overwrite converted model or provenance")
import numpy as np # noqa: PLC0415
import torch # noqa: PLC0415

# This is intentionally the only use of weights_only=False in the utility.
# An untrusted pickle can execute arbitrary code during this operation.
original = torch.load(source, map_location="cpu", weights_only=False)
if not isinstance(original, dict) or not isinstance(original.get("model"), dict):
raise ValueError("Expected a DeepMD training checkpoint with a model mapping")
model = original["model"]
extra = model.get("_extra_state")
if not isinstance(extra, dict) or not isinstance(extra.get("model_params"), dict):
raise ValueError("Missing DeepMD model._extra_state.model_params")

changes: list[str] = []
converted = _normalize(model, torch=torch, numpy=np, changes=changes, path="model")
before = dict(_tensors(model))
after = dict(_tensors(converted))
if not before or before.keys() != after.keys():
raise ValueError("Model tensor names changed or no model tensors found")
for name in before:
a, b = before[name], after[name]
if a.dtype != b.dtype or a.shape != b.shape or not torch.equal(a, b):
raise ValueError(f"Tensor identity changed during conversion: {name}")

target.parent.mkdir(parents=True, exist_ok=True)
fd, temp_name = tempfile.mkstemp(
prefix=f".{target.name}.", suffix=".tmp", dir=target.parent
)
os.close(fd)
temp = Path(temp_name)
try:
torch.save({"model": converted}, temp)
# The same restricted unpickler that DeePMD uses must accept our output.
verified = torch.load(temp, map_location="cpu", weights_only=True)
tensors = dict(_tensors(verified["model"]))
if tensors.keys() != before.keys() or any(
before[name].dtype != tensors[name].dtype
or before[name].shape != tensors[name].shape
or not torch.equal(before[name], tensors[name])
for name in before
):
raise ValueError("The saved checkpoint did not preserve model tensors")
record = {
"schema": "mliport.dpa-checkpoint-conversion/1",
"source_path": str(source.resolve()),
"source_sha256": _sha256(source),
"output_path": str(target.resolve()),
"output_sha256": _sha256(temp),
"torch_version": torch.__version__,
"tensor_count": len(before),
"tensor_dtypes": sorted({str(t.dtype) for t in before.values()}),
"numeric_conversion": changes,
"dropped_top_level_keys": sorted(str(k) for k in original if k != "model"),
"verification": "weights_only=True reload + tensor names/dtypes/shapes/values equality",
"warning": "Only verified the serialization contract, not DPA predictions or energy references",
}
# Publish both only after all checks pass. They contain no model tensors.
# On an error, leave no file that could be mistaken for verified output.
os.replace(temp, target)
try:
provenance_file.write_text(
json.dumps(record, indent=2, ensure_ascii=False) + "\n",
encoding="utf-8",
)
except BaseException:
target.unlink(missing_ok=True)
raise
return record
finally:
temp.unlink(missing_ok=True)


def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument(
"source", type=Path, help="Original trusted DeepMD training .pt"
)
parser.add_argument("target", type=Path, help="New inference-compatible .pt")
parser.add_argument(
"--i-trust-this-file",
action="store_true",
help="Required: allow unsafe pickle deserialization of this specific source",
)
args = parser.parse_args()
details = convert_checkpoint(
args.source, args.target, trusted=args.i_trust_this_file
)
print(json.dumps(details, indent=2, ensure_ascii=False))


if __name__ == "__main__":
main()
76 changes: 76 additions & 0 deletions tests/mliport/mliport/test_dpa_checkpoint_conversion.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
"""Trust-gated DPA checkpoint conversion regression tests."""

from __future__ import annotations

from pathlib import Path

import numpy as np
import pytest
import torch

from scripts.convert_dpa_checkpoint import convert_checkpoint


def _checkpoint(path: Path):
original = {
"model": {
"layer.weight": torch.tensor([[1.0, 2.25]], dtype=torch.float64),
"_extra_state": {
"model_params": {"type_map": ["Li", "S"], "precision": "float64"},
"train_infos": {"lr": np.float64(0.0125)},
},
},
"optimizer": {"param_groups": [{"lr": np.float64(0.0125)}]},
}
torch.save(original, path)
return original


def test_trusted_conversion_preserves_double_tensor_and_model_metadata(tmp_path):
source, target = tmp_path / "training.pt", tmp_path / "inference.pt"
original = _checkpoint(source)
source_bytes = source.read_bytes()
record = convert_checkpoint(source, target, trusted=True)
safe = torch.load(target, map_location="cpu", weights_only=True)
assert set(safe) == {"model"}
assert safe["model"]["_extra_state"]["train_infos"]["lr"] == 0.0125
assert (
safe["model"]["_extra_state"]["model_params"]
== original["model"]["_extra_state"]["model_params"]
)
assert torch.equal(safe["model"]["layer.weight"], original["model"]["layer.weight"])
assert safe["model"]["layer.weight"].dtype == torch.float64
assert source.read_bytes() == source_bytes
assert record["tensor_dtypes"] == ["torch.float64"]
assert record["tensor_count"] == 1
assert "optimizer" in record["dropped_top_level_keys"]
assert target.with_suffix(".conversion.json").is_file()


def test_untrusted_conversion_never_unpickles_or_writes(tmp_path):
source, target = tmp_path / "training.pt", tmp_path / "inference.pt"
source.write_bytes(b"not a checkpoint")
with pytest.raises(PermissionError, match="explicit trust"):
convert_checkpoint(source, target, trusted=False)
assert not target.exists()


def test_original_and_existing_target_are_protected(tmp_path):
source, target = tmp_path / "training.pt", tmp_path / "inference.pt"
_checkpoint(source)
with pytest.raises(ValueError, match="Never overwrite"):
convert_checkpoint(source, source, trusted=True)
target.write_bytes(b"existing output")
with pytest.raises(FileExistsError):
convert_checkpoint(source, target, trusted=True)
assert target.read_bytes() == b"existing output"


def test_unknown_model_extra_state_fails_closed_without_writing(tmp_path):
source, target = tmp_path / "training.pt", tmp_path / "inference.pt"
data = _checkpoint(source)
data["model"]["_extra_state"]["unhandled"] = np.array([1, 2])
torch.save(data, source)
with pytest.raises(TypeError, match="Unsupported value"):
convert_checkpoint(source, target, trusted=True)
assert not target.exists()
Loading