99. DFTBench 字段 → 概念反查表¶

本篇是反向查询工具。当你在 benchmark 数据、QE 输入/输出、评分代码里遇到不懂的字段，到这里查它的物理含义和所在化简步骤。

A. benchmark/materials/*.json 字段¶

每个 *_materials.json 文件遵循统一 schema：

{
  "category": "Semiconductor",
  "materials": [
    {
      "id": "0",
      "info": {
        "formula": "Si",
        "structure": "diamond",
        "atoms_per_primitive_cell": 2,
        "space_group": "Fd-3m"
      },
      "parameters": {},
      "ground_truth": {},
      "metadata": {}
    }
  ]
}

字段详解¶

字段	物理含义	化简步骤	详见
`category`	材料类别（10 种之一）	—	`31-material-categories.md`
`id`	类别内编号（0-9）	—	—
`info.formula`	化学式（Si, GaAs, Fe₃O₄ 等）	—	—
`info.structure`	晶体原型（diamond, zinc blende, perovskite...）	化简 7	`17-bloch-bz.md`
`info.atoms_per_primitive_cell`	原胞中的原子数	化简 7	`17-bloch-bz.md`
`info.space_group`	空间群符号（Fd-3m, P4mm...）	化简 10	`20-symmetry.md`
`parameters`	每种材料的建议计算参数（当前为空）	化简 8, 9, 11, 12	—
`ground_truth`	参考值（当前全空，这是 benchmark 的核心问题）	所有	`doc/reports/report_ground_truth.md`
`metadata`	额外信息（当前为空）	—	—

`structure` 原型枚举（benchmark 中出现的所有值）¶

原型名	代表材料	空间群	原胞原子数
diamond	Si, Ge, C	Fd-3m (227)	2
zinc blende	GaAs, InP, ZnS	F-43m (216)	2
rocksalt	NaCl, MgO, LiF	Fm-3m (225)	2
wurtzite	ZnO, AlN, GaN	P6₃mc (186)	4
rutile	SiO₂（部分相）, MgF₂	P4₂/mnm (136)	6
trigonal	α-quartz SiO₂, LiNbO₃	多种	9-30
hexagonal	部分 BN	P6₃/mmc (194)	4
perovskite	BaTiO₃, PbTiO₃	Pm-3m 立方/ P4mm 四方	5
rhombohedral	BiFeO₃, LiNbO₃	R3c/R3m/R-3m	10
orthorhombic	SnSe, HfO₂	Pbcm, Pnma	8-12
fluorite	CaF₂, BaF₂	Fm-3m (225)	3
antifluorite	Mg₂Si, Mg₂Ge	Fm-3m (225)	3
corundum	Al₂O₃, Cr₂O₃	R-3c (167)	10
bcc	Li, Na, K, Fe, W, Mo	Im-3m (229)	1
fcc	Al, Cu, Ag, Au	Fm-3m (225)	1
skutterudite	CoSb₃	Im-3 (204)	32
layered	TaS₂, NbSe₂	P6₃/mmc, P-6m2	3-6
high-pressure hydride	LaH₁₀	Fm-3m (225)（高压相）	11
topological insulator	Bi₂Se₃, Bi₂Te₃	R-3m (166)	5
Dirac semimetal	Cd₃As₂, Na₃Bi	I4₁/acd, P6₃/mmc	大原胞
semimetal	Bi, Sb	R-3m (166)	2
topological crystalline	SnTe, PbTe	Fm-3m (225)	2
ferromagnetic metal	Fe, Co, Ni	Im-3m, Fm-3m, P6₃/mmc	1-2
antiferromagnetic / antiferromagnetic oxide / antiferromagnetic metal	Cr, Mn, NiO, MnO, FeO, Cr₂O₃	多种	超胞翻倍
ferrimagnetic	Fe₃O₄	Fd-3m (227)	14
conventional superconductor	Nb, V, Pb, Al, Sn	bcc/fcc	1
phonon-mediated	MgB₂	P6/mmm (191)	3
iron-based	FeSe	P4/nmm (129)	2

B. benchmark/questions/*.json 字段¶

每个 task 模板遵循：

{
  "name": "vc_relax",
  "description": "...",
  "prompt_template": "...",
  "required_ground_truth": ["relaxed_structure"],
  "default_parameters": {}
}

task 类型枚举¶

task name	任务目标	典型命令	详见
`vc_relax`	变胞结构弛豫	`pw.x calculation='vc-relax'`	`22-bfgs-relax.md`
`vc_relax_low_acc`	20 meV/atom 精度	同上，较松阈值	`22-bfgs-relax.md`
`vc_relax_medium_acc`	10 meV/atom 精度	同上	`22-bfgs-relax.md`
`vc_relax_high_acc`	1 meV/atom 精度	同上，严格阈值	`22-bfgs-relax.md`
`vc_relax_scf`	弛豫后再 SCF 报总能量	vc-relax → scf	`21-scf-iteration.md` + `22-bfgs-relax.md`
`scf_energy`	单点 SCF 能量（不弛豫）	`pw.x calculation='scf'`	`21-scf-iteration.md`
`band_gap`	带隙计算	vc-relax → scf → nscf → bands	`30-observables.md` 组 2
`dos`	态密度	vc-relax → scf → nscf → bands → dos.x	`30-observables.md` 组 2
`dos_high_acc`	1 meV 分辨率 DOS	同上，高精度	同上

`required_ground_truth` 字段枚举¶

字段	物理含义	评分逻辑
`relaxed_structure`	弛豫后的完整结构	展开为 `a, b, c, α, β, γ, space_group, ...` 后评分
`total_energy_ev_per_fu`	总能量（eV/formula unit）	相对误差评分（但 compare.py 当前未实现此字段）

prompt 模板占位符¶

占位符	来源
`{material_context}`	由 `MaterialRecord.query_context()` 生成，形如 `formula=Si structure=diamond atoms_per_primitive_cell=2 space_group=Fd-3m`
`{material_summary}`	更可读的完整描述
`{parameter_text}`	参数块（目前多为空）
`{parameter_context}`	参数短句，形如 "Set etot_conv_thr=..., use a gamma-centered grid grid, make a educated guess for ..."
`{pseudopotential_text}`	"Use {LDA/PBE/PBEsol} pseudopotentials"

C. src/evaluate/compare.py：评分规则¶

COMPARISON_RULES = {
    "a": "relative",          # 相对误差
    "b": "relative",
    "c": "relative",
    "alpha": "relative",
    "beta": "relative",
    "gamma": "relative",
    "space_group": "exact",   # 字符串完全匹配
    "space_group_number": "exact",
    "point_group": "exact",
    "crystal_system": "exact",
}

字段详解¶

评分字段	物理含义	化简步骤	详见
`a`, `b`, `c`	原胞三个边长（Å）	化简 12 输出	`22-bfgs-relax.md`
`alpha`, `beta`, `gamma`	原胞三个夹角（度）	化简 12 输出	`22-bfgs-relax.md`
`space_group`	空间群国际符号（如 "Fd-3m"）	化简 10 分析	`20-symmetry.md`
`space_group_number`	空间群编号（1-230）	化简 10	`20-symmetry.md`
`point_group`	点群符号（如 "m-3m"）	化简 10	`20-symmetry.md`
`crystal_system`	晶系（cubic, hexagonal, ...）	化简 10	`20-symmetry.md`

评分逻辑¶

relative：rel_error = |eval - gt| / max(|gt|, 1e-12)，取所有 relative 字段的最大值作为 max_rel_error
exact：字符串全等，任何不等则 all_exact_match=False

当前问题：ground_truth 全空 → 所有字段比较都是 inf 或 False，评分无意义。详见 doc/reports/report_ground_truth.md。

D. QE 输入文件字段¶

参考 /home/weilin/workspace/TritonDFT/tritonDFT-src/test_manual/si.vc-relax.in：

`&CONTROL` 块¶

字段	物理含义	化简步骤
`calculation`	任务类型（`scf`/`nscf`/`bands`/`relax`/`vc-relax`/`md`）	化简 11/12
`outdir`	输出目录	—
`pseudo_dir`	赝势文件目录	化简 6
`prefix`	运行 ID	—
`tprnfor`	是否打印力	化简 12
`tstress`	是否打印应力	化简 12
`verbosity`	`low`/`high`	—

`&SYSTEM` 块¶

字段	物理含义	化简步骤
`ibrav`	Bravais 晶格类型（0-14）	化简 7
`celldm(1..6)`	晶格参数（依赖 ibrav）	化简 7
`nat`	原子总数	—
`ntyp`	原子种类数	—
`ecutwfc`	波函数截断能（Ry）	化简 8
`ecutrho`	密度截断能（Ry）	化简 8
`nbnd`	计算的能带数	化简 11
`nspin`	1=非极化，2=自旋极化	化简 2
`starting_magnetization(i)`	初始磁矩（磁性必要）	化简 11
`occupations`	`fixed`/`smearing`/`tetrahedra`	化简 9
`smearing`	`gaussian`/`mv`/`fd`	化简 9
`degauss`	smearing 宽度（Ry）	化简 9
`lspinorb`	自旋轨道耦合	化简 2 扩展
`noncolin`	非共线磁性	—
`input_dft`	强制泛函（如 'hse'）	化简 5

`&ELECTRONS` 块¶

字段	物理含义	化简步骤
`conv_thr`	SCF 能量收敛阈值（Ry）	化简 11
`mixing_mode`	`plain`/`TF`/`local-TF`/`broyden`	化简 11
`mixing_beta`	混合系数 α（0-1）	化简 11
`mixing_ndim`	Broyden 历史长度	化简 11
`electron_maxstep`	最大 SCF 步数	化简 11
`diagonalization`	`david`/`cg`/`ppcg`/`paro`	化简 11

`&IONS` 块（relax/vc-relax 需要）¶

字段	物理含义	化简步骤
`ion_dynamics`	`bfgs`/`damp`/`verlet`	化简 12

`&CELL` 块（vc-relax 需要）¶

字段	物理含义	化简步骤
`cell_dynamics`	`bfgs`/`none`	化简 12
`cell_dofree`	哪些晶格自由度可变	化简 12
`cell_factor`	胞外平面波扩展因子	化简 12
`press`	目标压强（kbar）	化简 12
`press_conv_thr`	压强收敛阈值（kbar）	化简 12
`etot_conv_thr`	总能量收敛阈值（Ry）	化简 12
`forc_conv_thr`	力收敛阈值（Ry/bohr）	化简 12

数据块¶

块	内容	化简步骤
`ATOMIC_SPECIES`	原子种类 + 质量 + 赝势文件名	化简 1 + 6
`ATOMIC_POSITIONS {alat/bohr/angstrom/crystal}`	原子坐标	化简 1
`CELL_PARAMETERS {alat/bohr/angstrom}`	晶格向量（ibrav=0 时必需）	化简 7
`K_POINTS {automatic/gamma/crystal/tpiba/crystal_b}`	k 点采样	化简 9

E. QE 输出文件关键字段¶

输出行	含义	化简步骤
`Program PWSCF v.7.5 starts on ...`	QE 启动	—
`Parallel version (MPI)`	是否并行	—
`number of atoms/cell`	原胞原子数	—
`number of atomic types`	原子种类数	—
`number of electrons`	电子总数	化简 6 价电子
`number of Kohn-Sham states`	能带数（≈ nbnd）	化简 11
`kinetic-energy cutoff`	`ecutwfc`	化简 8
`charge density cutoff`	`ecutrho`	化简 8
`convergence threshold`	`conv_thr`	化简 11
`mixing beta`	混合系数	化简 11
`number of k points`	压缩后的不可约 k 点数	化简 10
`iteration # N`, `ethr = ...`	SCF 迭代状态	化简 11
`convergence has been achieved in N iterations`	SCF 收敛	化简 11
`Davidson diagonalization with overlap`	对角化算法	化简 11
`! total energy = ... Ry`	最终总能量	化简 11
`estimated scf accuracy <`	当前 SCF 精度	化简 11
`the Fermi energy is ... eV`	费米能级	化简 11
`Forces acting on atoms (cartesian axes, Ry/au)`	原子受力	化简 12
`total stress ... P = ... kbar`	应力张量 + 平均压强	化简 12
`BFGS Geometry Optimization`	进入 BFGS	化简 12
`number of bfgs steps = N`	BFGS 步数计数	化简 12
`new unit-cell volume = ...`	新体积（vc-relax）	化简 12
`Begin final coordinates`	弛豫完成后的最终结构	化简 12
`CELL_PARAMETERS (alat= ...)`	最终晶格向量	化简 12
`ATOMIC_POSITIONS (crystal)`	最终原子坐标	化简 12
`Final enthalpy = ... Ry`	最终焓（vc-relax 目标）	化简 12
`JOB DONE.`	QE 正常结束	—

F. 常见速查¶

"为什么我的 Ge 算错了？"¶

关键字：ecutwfc=40 Ry + Ge 3d 半芯态
化简步骤：6（赝势）+ 8（基组）
笔记：16-pseudopotential.md、18-plane-wave-basis.md
规则：Ge 需要 60+ Ry，40 Ry 基组不完备导致能量面失真

"为什么我的 Fe 算不收敛？"¶

关键字：SCF 不收敛 / 磁性坍缩
化简步骤：11（SCF）
笔记：21-scf-iteration.md、31-material-categories.md 第 6 节
规则：nspin=2 + starting_magnetization + 小 mixing_beta

"为什么我的带隙比实验值小 30%？"¶

关键字：DFT band gap problem
化简步骤：5（XC 泛函）
笔记：15-xc-functional.md、30-observables.md 组 2
规则：LDA/GGA 系统性低估；用 HSE06 改善但贵 10-100×

"`ibrav=2` vs `ibrav=0` 哪个对？"¶

关键字：Bravais 格子 vs 自定义
化简步骤：7
笔记：17-bloch-bz.md
规则：ibrav=2 是 fcc 快捷方式（只需 celldm(1)）；ibrav=0 需要显式给 CELL_PARAMETERS，更通用但容易写错

"k 点 8×8×8 够不够？"¶

关键字：k-point convergence
化简步骤：9
笔记：19-kpoints.md
规则：绝缘体通常够，金属不一定；必须做收敛性测试

G. 下一步¶

完成反查表后，去做自测：99-self-test.md

99. DFTBench 字段 → 概念反查表¶

A. benchmark/materials/*.json 字段¶

字段详解¶

structure 原型枚举（benchmark 中出现的所有值）¶

B. benchmark/questions/*.json 字段¶

task 类型枚举¶

required_ground_truth 字段枚举¶

prompt 模板占位符¶

C. src/evaluate/compare.py：评分规则¶

字段详解¶

评分逻辑¶

D. QE 输入文件字段¶

&CONTROL 块¶

&SYSTEM 块¶

&ELECTRONS 块¶

&IONS 块（relax/vc-relax 需要）¶

&CELL 块（vc-relax 需要）¶

数据块¶

E. QE 输出文件关键字段¶

F. 常见速查¶

"为什么我的 Ge 算错了？"¶

"为什么我的 Fe 算不收敛？"¶

"为什么我的带隙比实验值小 30%？"¶

"ibrav=2 vs ibrav=0 哪个对？"¶

"k 点 8×8×8 够不够？"¶

G. 下一步¶

`structure` 原型枚举（benchmark 中出现的所有值）¶

`required_ground_truth` 字段枚举¶

`&CONTROL` 块¶

`&SYSTEM` 块¶

`&ELECTRONS` 块¶

`&IONS` 块（relax/vc-relax 需要）¶

`&CELL` 块（vc-relax 需要）¶

"`ibrav=2` vs `ibrav=0` 哪个对？"¶