---
title: Document
status: active
audience: Developers
last-updated: 2026-10-11
owner: Docs Owner
---

# 参数校验与约束（Validation Rules）

- Status: active
- Audience: Developers
- Last-Updated: 2026-10-11

本文件用于作为参数校验规则的单一权威来源。

本文档说明了 DP-EVA 系统中各参数的校验逻辑和约束条件，这些规则由 Pydantic 验证器在运行时强制执行。

## 0. 配置迁移与未知字段

CLI 的配置读取顺序固定为：读取源 JSON → 在内存副本上迁移受支持的旧扁平提交字段 → 解析相对路径 → 使用严格模型校验 → 提交工作流。源 JSON 永不原位改写。

所有公开配置模型使用 `extra="forbid"`。未知或拼写错误的字段会在提交前触发 `ValidationError`，不会静默采用默认值。兼容迁移仅处理下列顶层字段，并将其移入 `submission`：

| 旧字段 | 规范字段 | 退役目标 |
| :--- | :--- | :--- |
| `backend`（值为 `local` 或 `slurm`） | `submission.backend` | `1.0` |
| `slurm_config` | `submission.slurm_config` | `1.0` |
| `env_setup` | `submission.env_setup` | `1.0` |
| `slurm_array` | `submission.slurm_array` | `1.0` |
| `slurm_array_task_limit` | `submission.slurm_array_task_limit` | `1.0` |

每个迁移字段都会输出形如 `legacy config field backend; use submission.backend; removal target 1.0` 的 warning。探索工作流的 `backend="atst-tools"` 是工作流自身字段，不会被误判为提交 backend。

## 1. 基础类型校验
所有参数必须符合定义的 Python 类型。
*   **Path**: 必须是字符串或 Path 对象，且部分路径必须在文件系统中实际存在（参见具体参数说明）。
*   **Int/Float**: 会自动尝试进行类型转换（如字符串 "1" 转为整数 1），转换失败则报错。

## 2. 数值范围约束
| 参数 | 约束条件 | 错误示例 |
| :--- | :--- | :--- |
| `omp_threads` | `>= 1` (若为数字) | `0`, `-1` |
| `num_models` | `>= 3` | `2` (QbC UQ 至少需要 3 个模型) |
| `uq_trust_ratio` | `0.0 <= x <= 1.0` | `1.5`, `-0.1` |
| `uq_trust_width` | `> 0.0` | `0.0`, `-0.5` |
| `direct_n_clusters` | `> 0` (若设置) | `0` |
| `direct_k` | `>= 1` | `0` |

## 3. 逻辑依赖校验 (Cross-Field Validation)

### 3.1 采集工作流 (CollectionConfig)

#### 3.1.1 UQ Trust Mode 依赖
*   **规则**: 当 `uq_trust_mode` 为 `"manual"` 时，必须提供手动边界参数。
*   **规则**: 当 `uq_trust_mode` 为 `"no_filter"` 时，不启用信任区筛选，手动边界参数将被忽略。
*   **QbC 检查**:
    *   必须提供 `uq_qbc_trust_lo`。
    *   必须提供 `uq_qbc_trust_hi` **或者** `uq_qbc_trust_width` (此时 `hi = lo + width`)。
*   **RND 检查**:
    *   必须提供 `uq_rnd_rescaled_trust_lo`。
    *   必须提供 `uq_rnd_rescaled_trust_hi` **或者** `uq_rnd_rescaled_trust_width`。
*   **报错信息**: `ValueError: In 'manual' trust mode, uq_qbc_trust_lo must be provided.`

#### 3.1.2 采样参数依赖
*   **规则**: 采样策略由 `sampler_type` 控制：
    *   `sampler_type="direct"`：使用 `direct_n_clusters/direct_k/direct_thr_init`。
    *   `sampler_type="2-direct"`：使用 `step1_*` 与 `step2_*` 参数组。
*   **规则**: 若 `direct_n_clusters` 显式给定，必须 `> 0`。

#### 3.1.3 出图分层开关依赖
*   **规则**: `enable_diagnostic_plots` 默认 `False`，仅输出 Core 层图像。
*   **规则**: 当 `enable_diagnostic_plots=True` 时，仅在满足真值和数据前置条件时输出 Diagnostic 层 parity 图像。
*   **可观测性**: 跳过图像必须输出统一 `reason` 字段，且生成/跳过清单在日志中可审计。

### 3.2 特征工作流 (FeatureConfig)

#### 3.2.1 自动保存目录 (Auto Savedir)
*   **规则**: 如果用户未指定 `savedir`，系统会自动根据 `model_path` 和 `data_path` 生成默认保存路径。
*   **逻辑**: `savedir = "desc-{model_stem}-{data_name}"`

#### 3.2.2 Feature exporter
*   **默认**: `feature_exporter="eval_desc"`，CLI 模式调用 `dp eval-desc`，输出旧 `.npy` descriptor。
*   **Embed**: `feature_exporter="embed"` 调用 `dp embed`，输出 `savedir/embedding.hdf5`。
*   **特征映射**: `feature_kind="descriptor"` 对应 HDF5 `descriptor`；`feature_kind="fitting_last_layer"` 对应 HDF5 `atomic_feature`。
*   **精度**: `embedding_dtype` 允许 `fp32`、`fp64`、`native`，默认 `fp32`。

#### 3.2.3 Collect feature input
*   **规则**: `CollectionConfig.desc_dir` 与 `training_desc_dir` 可指向 `.npy` descriptor 目录、单个 HDF5 文件，或包含 `embedding.hdf5` 的目录。
*   **特征映射**: `CollectionConfig.desc_feature_kind="descriptor"` 默认读取 HDF5 `descriptor`；`"fitting_last_layer"` 读取 HDF5 `atomic_feature`。
*   **多池命名**: 递归 HDF5 目录会把 `embedding.hdf5` 相对 `desc_dir` 的父目录作为 system 前缀，例如 `desc/poolA/embedding.hdf5` 生成 `poolA/sys1-0`。
*   **LLPR**: `llpr_train_feature_dir` 与 `llpr_candidate_feature_dir` 可直接读取 HDF5 `atomic_feature`。

### 3.3 提交配置 (SubmissionConfig)

#### 3.3.1 环境变量格式化
*   **规则**: `env_setup` 字段支持字符串或字符串列表。
*   **转换**: 如果输入为列表 `["cmd1", "cmd2"]`，会自动转换为多行字符串 `"cmd1
cmd2"`。

## 4. 路径存在性校验
以下参数在初始化时会检查文件/目录是否存在，若不存在将抛出 `ValidationError` (或后续运行时错误)：

*   `CollectionConfig.desc_dir`
*   `CollectionConfig.testdata_dir`
*   `FeatureConfig.data_path`
*   `FeatureConfig.model_path`
*   `InferenceConfig.data_path`
*   `TrainingConfig.base_model_path`

## 5. 标注工作流校验 (LabelingConfig)

### 5.1 阈值与参数
*   `cleaning_thresholds`: 支持设置为 `null` 以跳过对特定物理量（如 `cohesive_energy`）的检查。
*   `kpt_criteria`: 必须 `> 0`。用于自动计算 K 点网格密度。
*   `labeling_task_classes`: 若启用 task class，`resource_mode="single_gpu"` 必须搭配 `launcher_mode="abacus"`；`resource_mode="multi_gpu_mpi"` 必须搭配 `launcher_mode="mpi_abacus"`。
*   普通 FP11 单卡 class 应设置 `ntasks=1`、`gpus_per_node=1`，且不加载 rank-map 或引用 `MAP_OPT`。多卡 MPI ABACUS class 才加载 SAI rank-map 并通过 `MAP_OPT` 组装 `mpirun`。

### 5.2 路径校验
*   `input_data_path`: 必须存在。
*   `pp_dir`: 必须存在。
*   `orb_dir`: 必须存在。