test-for-multiple-datapool 生产目录输入输出分析

test-for-multiple-datapool 生产目录输入输出分析#

  • Status: active

  • Audience: Developers

  • Last-Updated: 2026-10-11

目标目录：以仓库内多数据池测试资产为参照，例如 tests/ 中的相关集成测试输入输出目录。

本文档用于把生产级运行产物拆解为“输入资产 / 输出资产”，并将其映射到 DP-EVA 各 Workflow 的配置字段（对照 examples/recipes/）。

0. 相关方#

  • 开发者：维护 workflow 的输入输出约定与集成测试断言

  • 使用者：理解生产目录语义并定位产物位置

  • 平台维护：保障 Slurm/DeepMD 环境可复现

1. 目录结构概览（按语义分组）#

  • other_dpdata_all/

    • 多数据池候选集合（Multi Pool），目录结构为 Pool/System/set.000/*。

    • 典型候选 system 可能只包含 coord.npy/box.npy/type.raw/type_map.raw（无能量/力标注），用于推理与不确定性评估。

  • sampled_dpdata/

    • 训练用标注数据（Single Pool 的平铺 system 目录），目录结构为 System/set.000/*。

    • 典型训练 system 包含 energy.npy/force.npy/virial.npy 等标注数据。

  • desc_pool/

    • 候选集合（other_dpdata_all）对应的描述符输出（Feature Workflow 的产物）。

    • 目录结构为 Pool/System.npy，system 名称与候选 dpdata 中的 System 目录名一致。

  • desc_train/

    • 训练集合（sampled_dpdata）对应的描述符输出（Feature Workflow 的产物）。

    • 目录结构为 System.npy（平铺）。

  • 0/ 1/ 2/ 3/

    • Ensemble 训练输出目录（Training Workflow 的产物），每个目录代表一个 seed / 一个模型实例。

    • 典型文件：

      • input.json：DeepMD-kit dp train 输入（训练超参、数据路径等）。

      • model.ckpt.pt / model.ckpt-*.pt：训练权重（推理输入）。

      • lcurve.out：训练曲线。

      • test_val/：推理输出目录（Inference Workflow 的产物），包含 results.e.out/results.f.out/... 与 test.log。

  • dpeva_uq_result/

    • 数据采集与筛选（Collection Workflow）的输出目录（以 root_savedir 命名）。

    • 典型产物：

      • dataframe/*.csv：UQ/描述符/采样过程的中间与最终表格。

      • view/*.png：UQ 分布、PCA 覆盖度等可视化。

      • dpdata/sampled_dpdata/：筛选出的样本（保持 Multi Pool 结构）。

      • dpdata/other_dpdata/：未被选中的候选样本集合（保持 Multi Pool 结构）。

2. Workflow ↔ 输入/输出资产映射#

2.1 FeatureWorkflow（描述符生成）#

输入：

  • FeatureConfig.data_path

    • 候选描述符：指向 other_dpdata_all/

    • 训练描述符：指向 sampled_dpdata/

  • FeatureConfig.model_path

    • 用于 dp eval-desc 的模型（生产目录中可见 DPA-3.1-3M.pt / 或任意可用模型）。

  • FeatureConfig.model_head

  • submission.backend="slurm"

输出：

  • FeatureConfig.savedir

    • 候选：desc_pool/（Multi Pool 输出，Pool/System.npy）

    • 训练：desc_train/（Single Pool 输出，System.npy）

参考配置：

  • examples/recipes/feature_generation/config_feature.json

2.2 TrainingWorkflow（Ensemble 训练）#

输入：

  • TrainingConfig.training_data_path：指向 sampled_dpdata/（需要包含标注能量/力等）

  • TrainingConfig.input_json_path：DeepMD-kit 训练输入，例如生产目录内各模型下的 input.json

    • 生产 input.json 内 training.training_data.systems 指向 ../sampled_dpdata

  • TrainingConfig.base_model_path：预训练模型（例如 DPA-3.1-3M.pt）

  • TrainingConfig.num_models：对应输出子目录数量（生产为 4，对应 0..3/）

  • TrainingConfig.model_head

  • submission.backend="slurm"

输出：

  • work_dir/0..N-1/

    • model.ckpt.pt、checkpoint、lcurve.out 等

参考配置：

  • examples/recipes/training/config_train.json

2.3 InferenceWorkflow（候选集合推理）#

输入：

  • InferenceConfig.data_path：指向 other_dpdata_all/（候选集合，可无标注）

  • InferenceConfig.task_name：生产目录中为 test_val/

  • work_dir：训练输出所在目录；推理会扫描 0..N-1/ 并提交 dp test

  • InferenceConfig.model_head（如使用 Frozen/Head 模式）

  • submission.backend="slurm"

输出：

  • work_dir/<i>/<task_name>/

    • results.e.out/results.f.out/results.v.out 等

    • test.log：dp test 过程日志（可用于定位测试数据扫描情况）

参考配置：

  • examples/recipes/inference/config_infer.json

2.4 CollectionWorkflow（UQ + Filtering + Sampling + Export）#

输入（核心）：

  • CollectionConfig.desc_dir：候选描述符目录 desc_pool/

  • CollectionConfig.testdata_dir：候选 dpdata 目录 other_dpdata_all/

  • CollectionConfig.testing_dir：推理输出子目录名 test_val/

  • CollectionConfig.results_prefix：推理结果前缀 results

  • CollectionConfig.root_savedir：输出目录名，例如生产目录 dpeva_uq_result/

  • 采样参数（例如 direct_n_clusters/direct_k 或 sampler_type="2-direct" 等）

  • submission.backend="slurm"（生产配置中用 CPU 队列执行 collect）

输入（联合采样 Joint Sampling，可选）：

  • CollectionConfig.training_data_dir：训练 dpdata 目录 sampled_dpdata/

  • CollectionConfig.training_desc_dir：训练描述符目录 desc_train/

输出：

  • <root_savedir>/dataframe/*.csv

  • <root_savedir>/view/*.png

  • <root_savedir>/view/Final_sampled_PCAview_by_pool.png（仅 training_desc_dir 启用的 joint 模式生成；灰色全集背景 + sampled 按 pool 区分 + 图外多列图注）

  • <root_savedir>/dpdata/sampled_dpdata/<Pool>/<System>/...

  • <root_savedir>/dpdata/other_dpdata/<Pool>/<System>/...

参考配置：

  • 普通模式：examples/recipes/collection/config_collect_normal.json

  • 联合模式：examples/recipes/collection/config_collect_joint.json

2.5 AnalysisWorkflow（结果统计与可视化）#

输入：

  • AnalysisConfig.result_dir：指向某一个模型的推理输出目录，例如 0/test_val/

  • AnalysisConfig.type_map：元素列表（与体系一致）

输出：

  • AnalysisConfig.output_dir：分析产物目录（图表/统计汇总）

参考配置：

  • examples/recipes/analysis/config_analysis.json

3. 用于集成测试编排的关键观察#

  • 候选集合（other_dpdata_all）与训练集合（sampled_dpdata）在“是否包含标注”上语义不同：

    • 训练数据需要 energy/force/virial 等，用于 dp train

    • 候选数据可只包含结构信息，用于 dp test 生成预测并供 UQ 计算

  • 描述符输出命名规则与输入目录结构一致：

    • Multi Pool：输出 Pool/System.npy

    • Single Pool：输出 System.npy

  • 集成测试链路应以 DPEVA_TAG: WORKFLOW_FINISHED 作为每一步结束锚点；编排器通过监控 Slurm 输出日志定位完成节点再启动下一步

4. 异常处理#

  • 目录结构与本文档不一致：以实际目录为准，并在本文件补充“差异说明”（不要覆盖式修改历史结论）。

  • 训练数据缺标注：确认 sampled_dpdata 的 energy/force/virial 等是否存在。

  • 候选池缺 type_map.raw：优先补齐基础文件，否则元素映射可能错误。

5. 变更记录#

  • 2026-10-11：文档治理新鲜度复核，确认生产目录 I/O 拆解、workflow 映射与链接仍有效；无契约变更。

  • 2026-06-27：文档治理新鲜度复核，确认生产目录 I/O 拆解与 Workflow 映射仍作为测试专题参考；无契约变更。

  • 2026-03-26：补充 joint 多数据池新增总结图 Final_sampled_PCAview_by_pool.png 的触发条件与输出约定。

  • 2026-02-18：补齐生产目录 I/O 拆解与 Workflow 配置映射，并作为集成测试专题附录。

目录