卡片文档编写规范

目标：让用户从”模型哪里不行 → 训练集缺什么数据 → 选哪张卡 → 设什么参数 → 怎么判断改善”一路走通，而不是只解释每个参数的抽象含义。

语言风格

核心原则：像人在给你讲，不像在查 schema

参数说明是写给用户的，不是写给数据库的。如果 33 张卡、每张卡 5-20 个参数，全用同一个句式写，用户读 3 张就疲劳了。

禁止的写法

  • 每段以独立一行的 “类型：X。默认：Y。” 开头，然后再换行另起一段”解释”。类型和默认值是背景信息，不是段落主角。

  • 所有参数用同一个句式：“设置 XXX。”“决定是否 XXX。”“选择 XXX。”

  • 第一行和第二行语义重复——先说”设置位移距离”，再换行说”每个原子的位移”。

  • 通篇没有”你”——读者感觉是在看机器生成的规格书，不是有人在跟自己说话。

推荐写法

类型和默认值压缩成一句话，然后直接进入读者真正关心的内容。句式要有变化，要敢用”你”。

改前（机器感）：

### Max Distance（max_distance）
类型：`float`。默认：`0.3`。设置原子随机位移的最大距离。

每个原子的最大位移向量长度。这是绝对长度（单位 A），不是每个 Cartesian 分量的上限，也不是百分比。室温下典型固体原子振动幅度约 0.05~0.1A，设 0.15~0.3A 通常合适。含 H 等轻元素时考虑开启 `use_element_scaling` 单独调大 H 的幅度。

改后：

### Max Distance（max_distance）

`float`，默认 0.3。每个原子的最大位移，单位 A。

这个值不是 Cartesian 分量上限，也不是应变百分比——就是一个原子最多被挪多远。室温下原子振动幅度约 0.05~0.1A，设 0.15~0.3A 通常够用。如果体系含 H 等轻元素，H 的振幅天然更大，建议同时开启 `use_element_scaling` 单独给 H 调大。设到 0.3~0.5A 以上时，跑完务必抽查最近邻键长——这个量级已经可能拉断键了。

生效条件：开启 `use_element_scaling` 后，对在 `element_scalings` 中列出的元素，这个值会被覆盖。

变化点：

  • 第一行不再是独立的 “类型：X。默认：Y。”，而是压缩成 类型，默认值。描述。

  • “你”出现了——用户在读一个人写的东西

  • “如果…建议…” 替代了 “考虑开启”

  • “务必” 替代 “需要”——人的语气

  • 没有重复解释——不说一遍”设置位移”，又说一遍”位移长度”

  • 生效条件放在末尾，不和主描述抢节奏

句式要有变化

不要总用

偶尔换成

设置 XXX。

XXX 控制… / 这个值决定… / 改了它会影响…

决定是否 XXX。

打开之后… / 关了的话…

选择 XXX。

有两种模式：… / 可选值：… / 通常用…

建议…

你很可能只需要… / 大多数情况… / 除非…否则不用动

什么时候用”你”

以下情况应该用”你”：

  • 给建议时：“你很可能只需要默认值”

  • 警告时：“设太大可能会拉断键，你最好先抽查几个输出”

  • 解释选择时：“选 Exact 还是 Random 取决于你要不要严格配比”

以下情况不用：

  • 类型和枚举列表：“str，可选 sphere 或 cone”

  • 纯事实陈述：“PM 默认关闭，因为会显著增大输出规模”

必备章节

每张卡片页必须包含以下内容（标题可以调整，但信息不能缺）：

#

必须回答的问题

推荐标题

1

这张卡做什么

## 功能说明

2

模型出了什么问题要加这张卡，具体怎么操作，怎么验证改善

## 操作示例

3

每个参数的含义、类型、默认值和场景化建议

## 参数说明

4

可复制的 JSON 预设

## 推荐预设

5

和哪些卡片配合，怎么串

## 推荐组合

6

出错了怎么排查

## 常见问题

7

输出的 Config_type 标签是什么

## 输出标签

8

随机性、可复现条件

## 可复现性

适用场景与不适用场景 和 输入前提 不再要求独立章节——合并到操作示例（“什么时候加这张卡”）和参数说明中。

操作示例模板（最重要）

操作示例必须从训练集诊断出发，不能只写”设参数→得结果”。结构：

### 场景：模型在 [具体任务] 上 [具体失败表现]

[一句话诊断根因：训练集缺什么数据]

**输入：** [具体结构]
**目标：** [加入什么数据，预期解决什么问题]
**参数设置：** [具体参数值]
**输出：** [预期输出描述]
**怎么验证训练集质量改善：** [重训后应看到什么变化；不够的话下一步怎么调]

示例（Lattice Strain）：

### 场景：模型预测的弹性常数偏差太大

NEP 模型 C11 比 DFT 参考值高 15%。训练集所有结构都处在平衡体积附近，模型没见过被拉伸/压缩的晶胞，只能外推。

**输入：** 弛豫好的 Si 单胞
**目标：** 加入 ±2% 单轴应变结构，让模型在弹性区内有内插依据
**参数设置：** Axes=uniaxial, x_range=[-2, 2, 1]
**输出：** 5 个结构（-2%, -1%, 0%, +1%, +2%）
**怎么验证训练集质量改善：** 重训后 C11 应接近 DFT 参考值；不够则扩到 ±5%

示例（Magnetic Order）：

### 场景：FM 模型在 AFM 相上预测崩了

bcc Fe 的 NEP 模型，FM 构型推理准确但 AFM 构型能量误差是 FM 的 5 倍。训练集只有一种磁序。

**输入：** bcc Fe 晶体，已知 Fe 磁矩约 2.2 μB
**目标：** 生成 1 FM + 1 AFM + 8 PM，让模型见过不同磁序的局域磁环境
**参数设置：** magmom_map=Fe:2.2, gen_fm+gen_afm+gen_pm, pm_count=[8]
**输出：** 10 个不同磁序结构
**怎么验证训练集质量改善：** 重训后 FM/AFM 推理能量误差差距应显著缩小

示例（Random Doping）：

### 场景：纯元素模型在掺杂体系上完全失效

纯 Si 训练的 NEP 模型碰到 Si:Ge 合金，力误差跳了一个数量级。模型从来没见过 Ge 原子。

**输入：** 纯 Si 超胞
**目标：** 替换 3-8% 的 Si 为 Ge，每帧生成 20 个掺杂版本
**参数设置：** rules(target=Si,dopants=Ge:1.0,use=atomic_percent,percent=[3,8]), doping_type=Exact, max_structures=20
**输出：** 20 个掺杂结构
**怎么验证训练集质量改善：** 重训后 Si:Ge 测试集力 MAE 应回到纯 Si 水平

参数说明写法

只允许一种参数写法：每个 Params dataclass 字段必须有独立标题，标题里的 key 必须和代码字段完全一致。

参数少、没有明显功能组时，直接使用三级标题：

### Axes（axes）

类型：`str`。默认：`"uniaxial"`。决定对哪些晶格轴施加应变。

物理直觉：单轴用于补 C11/C22/C33；双轴用于泊松耦合；各向同性用于 EOS 或体模量附近采样。

| 选项 | 含义 | 什么时候选 |
|------|------|-----------|
| `uniaxial` | 一次只拉压一个轴 | 弹性常数、各向异性响应 |
| `biaxial` | 两两组合 | 面内耦合、薄膜应变 |
| `isotropic` | 三轴等比例 | 体积-能量曲线 |

参数多且存在天然功能组时，用三级标题表示功能组，用四级标题表示参数：

### 磁矩幅值来源

#### Magmom Map（magmom_map）

类型：`str`。默认：`""`。按元素指定磁矩幅值，例如 `Fe:2.2, Ni:0.6`。

物理直觉：已知元素局域磁矩时优先用它，避免不同磁性卡各自写一套不一致的幅值。

每个参数 block 固定包含：

  • 第一段：类型、默认值、这个参数实际控制什么。

  • 第二段：物理直觉或数据集使用场景，必须给量级或判断依据。

  • 枚举参数：加表格，列出选项、含义、什么时候选。

  • 条件参数：单独写 生效条件：...，不要让用户猜这个参数什么时候会被忽略。

禁止把多个 key 合在一个标题里，例如 Use Seed / Seed（use_seed / seed）。必须拆成 ### Use Seed（use_seed） 和 ### Seed（seed）。 禁止用占位表格，例如 以 UI 下拉项为准。枚举表必须写出真实选项，如 Sobol/Uniform、Collinear/Non-collinear、sphere/cone。 禁止用可套在任何参数上的模板句。物理直觉 必须能回答这个参数调大、调小、切换选项时具体改变了什么物理状态或数据分布。

禁止在参数说明中出现的内容：

  • UI Label、字段映射、控件标签、控件解释 等 UI 实现细节

  • 序列化格式说明（如”这是序列化结构字段，不是用户开关”）

  • params 作为独立参数块列出——这是内部实现，用户不需要知道

  • “先用默认值跑小样本；只有当你能明确说明它会改变当前结果分布时再主动偏离” 等模板填充句

常见问题

至少覆盖以下 3 类真问题（不要泛化模板句）：

  • 输出为空时这张卡最常见的原因

  • 输出不合理时具体怎么判断和回调

  • 参数冲突或越界时程序的实际行为

描述行为只能写代码的真实逻辑，不要臆造不存在的自动修复。

推荐组合

  • 必须写具体的卡片名，例如 Lattice Strain → Atomic Perturb，不要写”当前卡片 → 目标变换卡”。

  • 至少 2 条不同目的的组合建议。

推荐预设

  • 每档必须有实质性参数差异，不要三档 JSON 几乎一样。

  • 每个 JSON 附带一行说明，解释”这个预设解决什么问题，什么情况下选这一档”。

  • 如果卡片参数少、不需要三档，允许只保留 1-2 个预设。

禁止内容

  • “先保守再放大” 类空泛建议。

  • “先用默认值跑小样本” 类模板填充句。

  • 与卡片无关的统一 Physics caution 模板句。

  • “需要启用 XXX 对应行为时开启 / 希望保持默认时关闭” 类同义反复。

  • 没有输入、没有目标、没有验证条件的”伪示例”。

  • params 字段作为用户文档列在参数说明中。

维护命令

  • python tools/docs/audit_card_docs.py — 检查 key 一致性和默认值

  • python -m sphinx -W -b html docs/source docs/build/html — 文档构建