---
title: Upstream Software
status: active
audience: Users / Developers
last-updated: 2026-10-22
owner: Docs Owner
---

# 上游软件与依赖边界（Upstream Software）

- Status: active
- Audience: Users / Developers
- Last-Updated: 2026-10-22

本文档汇总 DP-EVA 的上游软件，说明其仓库位置、安装层级与在本项目中的职责边界。

## 1. DeePMD-kit（默认有界运行时依赖）

- 仓库地址：https://github.com/deepmodeling/deepmd-kit/
- 核心功能：机器学习势训练和推理平台。
- 安装层级：默认核心安装提供 `deepmd-kit>=3.1.2,<3.3`；需要明确 3.2
  qualification lane 时安装 `dpeva[deepmd]`。
- 版本边界：默认包络保留 3.1.2 起的运行兼容性，用户 extra 为
  `deepmd-kit>=3.2,<3.3`。这些范围是依赖解析边界，不能据此宣称其中每个版本
  的行为完全等价；3.1 运行时也不因此获得新的科学验证。
- 研究生产锁定：正式结果使用独立环境锁定 `deepmd-kit==3.2.0`，并在运行记录中保存 `dp --version`；不能用宽范围 extra 替代研究环境锁。
- 在 DP-EVA 中的作用：
  - 作为训练、测试与描述符评估的计算后端。
  - 通过 `dp` 命令参与 `train / infer / feature` 等流程。

### 1.1 3.2 compatibility qualification

DeepMD-kit 3.2 的能力状态由
`src/dpeva/compatibility/deepmd-3.2.json` 的精确 operation/backend/model/
artifact/data/environment key 管理。当前有 4 条 `supported` 记录（DPA4
pt test/eval-desc/embed，以及 `test + deepmd/lmdb`），其余能力仍保持明确的
experimental/unsupported/blocked 边界。SAI V100 qualification
JobID `1128260`、CPU contract JobID `1128442`、LMDB CPU contract JobID
`1893534` 与 LMDB SAI A/B JobID `1893546` 的 producer-issued JSON 证据已落库；
完整边界见仓库报告
`docs/reports/2026-09-04-deepmd-3.2-compatibility.md`。
其中 SAI aggregate 保留 DPA4 regular/EMA × `test`/`eval-desc`/`embed`
共六条历史 attestation；DPA4C periodic 路线仍为 experimental，未纳入这六条
promotion evidence。

发布或研究运行不得仅因版本号落在 `>=3.2,<3.3` 就晋级能力。只有精确验证命令、
CPU evidence，以及需要时的 SAI evidence 均存在并通过，Compatibility Owner 才能
在同一变更中更新 manifest 和报告。后续 SAI qualification 仍需新的显式授权、
不可变证据目录和完整 collector gate；当前结果不外推为科学精度或普遍 GPU/runtime
正确性。

`dpeva doctor` 将两条诊断 lane 分开：稳定的 `>=3.1.2,<3.3` 运行时包络用于
保留旧环境可用性，稳定 3.2 版本另行报告 qualification；3.1 不会被重新标记为
3.2 已验证能力。legacy runtime 上缺少 3.2 才有的 CLI surface 属于信息性检查，
不会把仍可用的旧环境整体判为 incompatible。

当前 manifest 共 21 条（4 supported、9 experimental、4 unsupported、4
blocked-upstream）。每条记录还声明 `verification_status` 与
`required_evidence`；`implemented` 必须绑定可收集的 pytest node，尚未具备测试的
train/fine-tune/freeze、LMDB fine-tune、pretrained alias 和 deploy 路线保持
planned，不能把占位命令当作已执行证据。LMDB `train` 已有 CPU contract 与
SAI 200-step execution A/B（仍为 experimental；训练曲线是随机 smoke，不作
等价性声明）；`test + deepmd/lmdb` 已由 CPU contract 与 SAI npy↔lmdb A/B
晋级 supported。LMDB 的 `eval-desc`/`embed` 记录由上游 issue #6034 标记为
blocked-upstream。2026-10-22 复核 `master` commit `a78bdfe8`：该 issue 仍
open，`eval_desc.py`/`embedding.py` 仍走 `expand_sys_str` + `DeepmdData`，
尚无实现 PR；因此保持 blocked-upstream。
`candidate-evaluation` 是供上层 generic preflight 使用的 policy capability，
不映射为 DeepMD CLI command。

## 2. dpdata

- 仓库地址：https://github.com/deepmodeling/dpdata
- 版本边界：`dpdata>=1.1,<1.2`（核心依赖）。读取 `deepmd/lmdb` 需要 `>=1.1`；
  `lmdb` 与 `msgpack` 由 dpdata 自身声明为运行依赖，DP-EVA 不新增直接依赖。
  `clean` 的原始 system 恢复路径使用 dpdata 1.1 的 LMDB codec 私有方法，因此在
  完成 1.2 兼容性验证前暂不放开上限。
- 核心功能：处理 `deepmd/npy`、`deepmd/npy/mixed`、`deepmd/lmdb` 等机器学习势结构数据格式。
- 在 DP-EVA 中的作用：
  - 负责数据集加载、结构读写与多系统数据组织。
  - 为采样、标注、分析等流程提供统一的数据结构接口。

### 2.1 数据格式支持矩阵（2026-09-20 实测）

| 消费方 | `deepmd/npy` / `npy/mixed` | `deepmd/lmdb` | 说明 |
|---|---|---|---|
| DP-EVA 读侧（`dpeva.io.dataset.load_systems`） | ✓ | ✓（dpdata≥1.1） | LMDB 只经 `dpdata.MultiSystems` 读取；体系分组口径为**组成分组** |
| `dp train`（`training_data` / `validation_data`） | ✓ | ✓（CPU contract + SAI 200-step smoke；experimental） | 要求 `systems` 为**单个字符串**路径，deepmd-kit 3.2 起原生流式读取；训练曲线随机性不作为格式等价门 |
| `dp test` | ✓ | ✓（supported） | 整个 LMDB 视作 1 个数据源，按 nloc 分组评测；`-d` 明细行序 = nloc 组升序，DP-EVA 用帧索引恢复归属 |
| `dp eval-desc` / `dp embed` | ✓ | ✗ | 上游基于 `expand_sys_str` + `DeepmdData`，无 LMDB 读取分支（3.2.0 GA、本地 dev 构建与 upstream master 均已核实）；DP-EVA 在提交作业前拒绝该组合 |

`dp test` 在 LMDB 上不保留目录级体系身份，但 DP-EVA 的 parser 现在通过
`frame_nlocs`/`frame_system_ids` 恢复帧级 system 归属（缺失元数据时 fail-loud）。
DeepMD-kit 3.2.0 的 `-d` 输出在 mixed-nloc LMDB 上只写首个 `[nloc=...]`
header 却写出完整行集；parser 只在总行数与帧索引一致时按 nloc 组序归属，
否则报错，不会静默猜测。
`infer`/`analysis` 的明细解析和 Clean 的原始 system 导出因此可用；
Clean 在没有 `frame_system_ids`/`system_info` 时 fail-loud；同一 source system
内 atom count 不同的混合帧当前仍拒绝合并，避免伪造固定 atom 轴。`dp test`
自报的聚合指标不受影响。

`label` integration 的帧去重使用 canonical element/geometry identity：
`type_map` 顺序和原子存储顺序不改变身份，标签数组随同一原子排列重排；
LMDB 缺少 `real_atom_types` 时以规范化 `atom_types` 作为元素身份。该等价声明
主要覆盖标准帧；npy/mixed 的 `real_atom_types` 与按组成分组的 LMDB 之间，
混合类型跨格式去重不保证命中，需保留原始 mixed 元数据或显式使用 npy 副本。

写出侧提供显式的 `dpeva.io.lmdb_writer.write_lmdb` 转换 API：
它按输入 system 顺序写出到 staging，回读校验 `frame_system_ids`、帧数和
nloc 组后原子发布；失败不会留下半成品或覆盖旧目标。缺少 `real_atom_names`
的 mixed source 会从显式 type map 注入临时名称。Label 的
`output_format` / `integration_output_format` 可选择 `deepmd/lmdb`，
输出为 `<output_dir>/dataset.lmdb`；默认仍保持 npy/mixed，不自动切换。

## 3. ABACUS

- 仓库地址：https://github.com/deepmodeling/abacus-develop
- 核心功能：开源第一性原理计算软件。
- 在 DP-EVA 中的作用：
  - 作为 Labeling 阶段的 DFT 计算后端。
  - 承担从候选结构到高精度标注数据的关键计算步骤。

## 4. ASE

- 仓库地址：https://gitlab.com/ase/ase
- 核心功能：原子结构对象、结构读写与计算器生态。
- 在 DP-EVA 中的作用：
  - 作为 `ase.Atoms` 的核心结构表示。
  - v0.8.0 起核心依赖下限为 `ase>=3.28.0`，与 `atst-tools` 运行环境对齐。

## 5. atst-tools（可选）

- 仓库地址：发布包为 `atst-tools`；开发期使用本地 `test/atst-tools` 参考检出（不在本仓库内）。
- 核心功能：基于 ASE 的轨迹探索与过渡态工具。
- 在 DP-EVA 中的作用：
  - 作为可选 exploration backend，首版支持 `md` 与 `relax`。
  - 通过 `dpeva[explore]` 安装，不进入核心依赖。
  - DPEVA 内部 ABACUS writer 参考其 vendored `abacuslite/io/generalio.py` 的 INPUT/KPT/STRU 子集。

## 6. ase-abacus（Legacy）

- 仓库地址：https://gitlab.com/1041176461/ase-abacus
- 状态：历史依赖。v0.8.0 当前主链路不再推荐安装，也不再要求 `ase.io.abacus`。
- 在 DP-EVA 中的历史作用：
  - 曾用于 Labeling 工作流的 ABACUS 输入生成。
  - 已由 `src/dpeva/labeling/abacus_io.py` 的内部最小 writer 替代。

## 7. 依赖分工总览

| 依赖 | 主要阶段 | 角色定位 |
|---|---|---|
| DeepMD-kit | Train / Infer / Feature（默认有界；显式 3.2 lane） | 机器学习势训练与推理计算引擎；默认 `>=3.1.2,<3.3`，用户 extra `dpeva[deepmd]`，研究生产锁定 `==3.2.0` |
| dpdata | Data IO / Labeling / Analysis | 结构数据格式与系统组织层；核心依赖下限 `>=1.1`（`deepmd/lmdb` 读取需要） |
| ABACUS | Labeling | 第一性原理计算后端 |
| ASE | Labeling / Exploration | 原子结构对象与结构读写基础 |
| atst-tools | Exploration（可选） | md/relax 轨迹探索后端 |
| ase-abacus | Legacy | 历史 ABACUS 输入生成依赖 |