跳转至

1.7 共享输入、约定与证据

1.7.1 完整共享输入与分析模板

1.7.1.1 输入块 1

runs/
  si_pbe_ec60_rho480_k8_scf/
    input.in
    output.out
    manifest.json
    pseudo.sha256
    extract.py
    launch.txt
    result.csv
  si_pbe_ec80_rho640_k8_scf/
    ...independent files, never overwrite the first point...

1.7.1.2 输入块 2

{
  "run_id": "si_pbe_ec60_rho480_k8_scf",
  "status": "not_run",
  "program": "pw.x",
  "qe_version": "record_actual_banner_before_analysis",
  "task": "fixed_geometry_scf",
  "geometry_source": "case_1_4_with_declared_lattice",
  "nat": 2,
  "ecutwfc_Ry": 60.0,
  "ecutrho_Ry": 480.0,
  "k_mesh": [8, 8, 8],
  "k_shift": [0, 0, 0],
  "functional": "verify_from_output",
  "pseudopotentials": [
    {"file": "Si.PBE.UPF", "sha256": "replace_with_actual_hash"}
  ],
  "energy_reference_run_ids": [],
  "analysis_status": "unverified_template"
}

1.7.1.3 输入块 3

from pathlib import Path
import csv
import json
import re

RY_TO_EV = 13.605693122994
energy_re = re.compile(
    r'^\s*!\s+total energy\s*=\s*([-+0-9.EeDd]+)\s+Ry',
    re.MULTILINE,
)
rows = []
for folder in sorted(Path('runs').iterdir()):
    if not folder.is_dir():
        continue
    manifest_path = folder / 'manifest.json'
    output_path = folder / 'output.out'
    if not manifest_path.exists() or not output_path.exists():
        raise RuntimeError(f'{folder}: missing manifest or output')
    meta = json.loads(manifest_path.read_text())
    if meta.get('task') != 'fixed_geometry_scf':
        raise RuntimeError(f'{folder}: unsupported task for this extractor')
    text = output_path.read_text(errors='replace')
    if 'JOB DONE.' not in text:
        raise RuntimeError(f'{folder}: no orderly completion marker')
    if 'convergence has been achieved' not in text:
        raise RuntimeError(f'{folder}: no SCF convergence evidence')
    if 'convergence NOT achieved' in text or 'Error in routine' in text:
        raise RuntimeError(f'{folder}: failure marker requires manual review')
    values = energy_re.findall(text)
    if len(values) != 1:
        raise RuntimeError(f'{folder}: expected one marked SCF energy, got {len(values)}')
    energy_ry = float(values[0].replace('D', 'E').replace('d', 'e'))
    nat = int(meta['nat'])
    if nat <= 0:
        raise RuntimeError(f'{folder}: invalid atom count')
    rows.append({
        'run_id': meta['run_id'],
        'nat': nat,
        'ecutwfc_Ry': meta['ecutwfc_Ry'],
        'ecutrho_Ry': meta['ecutrho_Ry'],
        'energy_Ry_cell': energy_ry,
        'energy_eV_atom': energy_ry * RY_TO_EV / nat,
    })
if not rows:
    raise RuntimeError('No SCF results were accepted')
with open('scf_results.csv', 'w', newline='') as f:
    writer = csv.DictWriter(f, fieldnames=list(rows[0]))
    writer.writeheader()
    writer.writerows(rows)

1.7.2 约定与学习证据

1.7.2.1 从可靠输入到可信材料结论

执行状态:** All numerical inputs below are original teaching templates, not executed calculations. No energy, gap, frequency, barrier, spectrum, speedup or convergence outcome is presented as a measured result. Values such as cutoffs, lattice constants and U parameters are starting choices for the stated exercise, never universal recommendations. Replace each illustrative UPF filename with the actual, verified file you obtained. Snippets headed “delta” modify a stated parent input; they are not standalone files. Figures are original production specifications, not generated data plots.

执行声明:以下所有数值输入均为原创教学模板,尚未执行。本文不把任何能量、带隙、频率、能垒、光谱、加速比或收敛结果冒充计算数据。截断能、晶格常数和 U 值等仅是练习的起点,绝非通用推荐。示例 UPF 文件名必须替换成你实际获得并核验的文件名。标为“修改项”的代码需要合并到指定母输入,不能独立运行。配图提供原创制作说明,不代表已有计算结果。

1.7.2.2 使用方式

请按依赖关系学习。1.1–1.4 建立环境与硅参考体系;后续案例会明确沿用参考还是引入新体系。除非研究目标就是改变哈密顿量,否则比较各组结果时必须保持其一致。可复现结果应包括精确输入、程序版本、赝势校验值、成功结束的输出、必要的重启文件、数据提取脚本与收敛论证。曲线截图不能替代原始证据。

以所安装版本随附的各程序手册为准,不要照搬旧教程。本文核验的官方页面标注为 7.5;公开网址可能随新版更新,应为自己的工作归档一份。可选模块,以及赝势类型、泛函、自旋处理与响应方法之间的兼容性,须针对具体构建检查。这是一门遵循 QE 原生工作流的课程:PW、PHonon、PP、turboTDDFPT、CP 和 PWneb 的语法及能力并不相同。

正确建立计算 — 1.1 installation and provenance; 1.2 pseudopotentials; 1.3 geometry and units; 1.4 first silicon SCF. 原子、分子与金属采样 — 2.1 H atom and spin; 2.2 H₂ binding curve; 2.3 Al metal; 2.4 coupled numerical convergence. 结构与力学 — 3.1 molecular relaxation; 3.2 variable-cell relaxation; 3.3 equation of state; 3.4 finite-strain elasticity. 电子结构解释 — 4.1 bands and DOS; 4.2 PDOS and density; 4.3 magnetism; 4.4 SOC; 4.5 DFT+U; 4.6 hybrids. 表面与缺陷 — 5.1 slabs; 5.2 adsorption; 5.3 charge rearrangement and work function; 5.4 vacancies and charged-defect caveats. 晶格响应 — 6.1 Γ phonons; 6.2 dispersions; 6.3 vibrational thermodynamics; 6.4 dielectric and Born response. 光谱与方法边界 — 7.1 independent-particle optical spectra; 7.2 molecular TDDFPT; 7.3 external GW/BSE workflow. 动力学、路径与生产计算 — 8.1 Born–Oppenheimer MD; 8.2 CP dynamics; 8.3 NEB; 8.4 restart and HPC.

1.7.2.3 单位与证据约定

  • PW cutoffs and SCF energy thresholds: Ry; 1 Ry ≈ 13.605693 eV. PW forces: Ry/bohr; 1 Ry/bohr ≈ 25.7110 eV/Å. A threshold of 1×10⁻⁴ Ry/bohr is approximately 0.00257 eV/Å.
  • PW 截断能及电子收敛阈值使用 Ry;力使用 Ry/bohr。切勿把相同数值直接当成 eV 或 eV/Å。
  • Explicit CELL_PARAMETERS angstrom and ATOMIC_POSITIONS angstrom use Å. crystal coordinates are dimensionless fractional coordinates. celldm(1) uses bohr, whereas A uses Å; do not specify both representations.
  • 显式标注 angstrom 时长度用 Å;crystal 为无量纲分数坐标。celldm(1) 用 bohr,A 用 Å,不能混填。
  • PW pressure input and common printed pressure column use kbar: 10 kbar = 1 GPa. Convert stress only after reading its printed unit and sign convention.
  • PW 压力输入与常见输出压力列以 kbar 为单位;10 kbar = 1 GPa。转换应力前必须核对输出单位及正负号。
  • pw.x time step is in Rydberg atomic time units, approximately 0.0483777 fs; cp.x uses Hartree atomic units, whose time unit is approximately 0.0241888 fs. The two programs do not share an interchangeable input deck.
  • pw.x 与 cp.x 的时间原子单位相差两倍;不能仅更换可执行文件就把一种分子动力学输入变成另一种。
  • DOS/PDOS energy grids commonly use eV; their broadening parameter degauss is in Ry. matdyn.x phonon DOS uses cm⁻¹. Always retain the file header.
  • DOS/PDOS 的能量网格常用 eV,而其 degauss 用 Ry;matdyn.x 声子态密度用 cm⁻¹。务必保留文件表头。

1.7.2.4 正确建立计算

1.7.2.5 附录 A:遇到不确定性就停止的可复现包

1.7.2.6 目录与命名约定

每个科学状态或收敛点使用独立且不被覆盖的运行目录。新计算与重启的区别应该写在元数据中,而不是从临时目录残留内容猜测。实用目录包含输入、标准输出、独立错误输出、清单、赝势校验值、提取脚本与精确启动命令。重启文件可另存,但要记录位置与保留规则。归档能量结论未必需要全部大波函数,但后续响应和后处理常常必须依赖它们。

参见上方输入块 1。

运行编号可编码便于阅读的差异,但精确信息以清单为准,不能依赖四舍五入后的文件夹名。结构优化应同时保存初始与最终几何。吸附或缺陷能应链接所有参考运行编号;任一参考改变后,衍生结果都应视为失效,直到重新计算。收敛图标题应说明目标物理量和参考设置,而不只是写“已收敛”。

1.7.2.7 原创最小清单

参见上方输入块 2。

清单刻意保留尚未核实的来源字段,只能用观察到的事实替换。输入生成成功不代表计算成功。可按“已准备→已启动→电子收敛→任务收敛→分析核验”记录状态,但不同任务并非完全相同。NSCF 完成不等于结构已优化,结构优化完成也不等于声子证明的极小值。

1.7.2.8 原创谨慎型 SCF 提取脚本

以下仅依赖 Python 标准库的脚本,为每个目录提取一个定几何 SCF 能量,仍属于未执行教学代码。缺少完成或收敛证据时它会拒绝,并把单位写入列名。它不是 MD、NEB、优化或 PH 输出解析器。扩展前应以实际成功和故意失败的日志测试。解析成功仍不能验证几何、赝势、k 采样或科学收敛。

参见上方输入块 3。

严格解析可避免将优化过程中的多个能量标记无声地归到错误状态。若版本格式不同,应根据经过测试的日志样例更新解析器,而不是取消所有检查。此处 nat 来自元数据,仍需与输出头部交叉核对。面向发表的流程还应核验输入哈希、赝势哈希和实际版本后,才接受比较。

1.7.2.9 附录 B:各程序负责什么

  • 在受支持方法下完成基态、自洽/非自洽/能带、力、应力、优化与 Born–Oppenheimer 动力学;保存目录是许多下游程序的起点。
  • bands.x — EN: rearranges/analyzes band data for plotting; it does not generate a new converged density. ZH:整理和分析能带数据,不生成新的自洽密度。
  • dos.x and projwfc.x — EN: total DOS and local-orbital projections from compatible saved data; their sampling and energy conventions must be checked. ZH:从相容保存数据生成总态密度和局域轨道投影,需核对采样与能量约定。
  • pp.x — EN: exports selected real-space fields; a field's integer selector determines what quantity is actually written. ZH:导出指定实空间场,整数选择项决定真正输出哪一种物理量。
  • ph.x — EN: density-functional perturbation calculations within supported combinations; it is not a universal response wrapper for every PW feature. ZH:在受支持组合下完成密度泛函微扰计算,并非所有 PW 功能都可直接接入。
  • q2r.x and matdyn.x — EN: transform dynamical matrices into force constants and evaluate interpolated modes/DOS. A denser interpolation grid cannot rescue missing coarse-grid information. ZH:把动力学矩阵变为力常数,并计算插值振型和 DOS;加密插值无法弥补原网格信息不足。
  • dynmat.x — EN: processes a dynamical matrix, including appropriate sum-rule and long-wavelength options. ZH:处理动力学矩阵,提供适用的和规则与长波选项。
  • hp.x — EN: computes Hubbard interaction parameters through its dedicated response workflow; choosing U by hand is a different operation. ZH:通过专用响应流程计算 Hubbard 参数,与手动选择 U 不同。
  • epsilon.x — EN: particular independent-particle optical/JDOS post-processing; source-level and method limitations matter. ZH:特定独立粒子光学/联合态密度后处理,需要注意实现和方法限制。
  • turbo_lanczos.x / turbo_spectrum.x — EN: response-chain generation and spectral reconstruction are separate stages with separate convergence checks. ZH:响应链生成与光谱重建是两阶段,各有独立收敛要求。
  • cp.x — EN: CP-specific electronic/ionic dynamics and its own restarts, units and initialization. ZH:具有自身单位、初始化与重启格式的 CP 电子/离子动力学程序。
  • neb.x — EN: an image-path driver using a PW engine; path convergence and electronic convergence are separate. ZH:调用 PW 引擎的图像路径程序,路径收敛与电子收敛不同。
  • Yambo, analysis scripts and viewers — EN: external dependencies, never implied to be installed or automatically validated with QE. ZH:属于外部依赖,不能默认它们已随 QE 安装或验证。

1.7.2.10 附录 C:各章考核与证据要求

1.7.2.11 基础

提交两个等价 Si 输入、赝势档案和一个成功 SCF 日志。解释为何改坐标单位后语法仍合法,而物理体系已经改变。评阅者无需运行代码就应能重算体积与价电子数。仅有赝势昵称或无标签截图,不能构成完整证据。

1.7.2.12 数值收敛

提交区分截断能、密度网格、k 点与展宽的测试矩阵,并预先声明目标量。用额外更严格测试支持工作参数,同时说明数值差异与物理意义。应明确认识到,总能稳定本身不足以证明应力、力或小能量差可靠。

1.7.2.13 结构响应

提交经过独立力/应力验证的最终结构、EOS 残差图及有限应变符号/单位审计。解释定胞优化原子与优化晶胞自由度的区别。两种体模量不一致时先诊断,不要直接取平均;平均不一致计算不等于估计误差。

1.7.2.14 电子结构

提交能带/DOS 采样比较、投影解释及一项受控进阶 DFT 研究。说明 SOC、DFT+U 与杂化泛函如何以不同方式改变模型,以及数值要求为何不同。报告必须区分人为选择参数、初始猜测、约束量与观察到的结果。

1.7.2.15 表面与缺陷

提交列明全部参考态的能量账本,并在适用时分别测试侧向尺寸、厚度与真空。先画清化学计量,再写能量公式。差分密度必须说明碎片几何和网格匹配;带电缺陷结果必须说明电子库与修正约定。

1.7.2.16 晶格动力学

提交 Γ 点修正前后比较、至少一个非网格点的直接与插值频率对照,以及 DOS 归一化检验。解释为何不能简单删除虚频后计算自由能。若声称结构稳定,应说明 q 覆盖范围及局限;Γ 点稳定不等于全布里渊区稳定。

1.7.2.17 光谱

提交方法边界图和一份独立收敛的光谱。说明每个展宽参数单位、包含及遗漏的相互作用。比较实验峰位前先展示收敛证据。经验位移必须明确写入方法,不能改称第一性原理准粒子修正。

1.7.2.18 生产计算准备

提交重启一致性测试、MD 步长/SCF 敏感性或 NEB 图像/力收敛报告,并附固定工作量性能比较。区分程序完成与科学任务完成。准确列明阻碍的报告,比用看似合理趋势填补缺失输出更可信。