dpa-phonon

dpa-phonon 是一个以 DPA 系列模型为核心的有限位移声子、三阶非谐声子与准谐近似工作流。 它用 YAML 管理结构、DPA3/DPA4、VASP/DFT、声子谱、振动热力学、RTA 晶格热 导率、多相 QHA 和 P–T 相图，并把临时文件与最终结果严格分开。全局命令为 ph。

普通 ph run 处理一个结构的谐声子，ph anh 使用 DeepMD + Phono3py 处理三阶 声子，ph qha 处理相同组成的多个晶相。项目不实现 VASP-DFPT、变组成凸包、 四阶声子、熔化或模型训练。

1. 安装

要求 Python 3.11 或更新版本。发布到 PyPI 后可直接安装：

python -m pip install dpa-phonon

发布前或需要固定 Git 版本时，可从公开仓库安装：

python -m pip install "dpa-phonon @ git+https://github.com/moliyes/phonon-kit.git@dpa-phonon-v0.4.0"
ph --version

GitHub 安装方式需要 Git。pip 会在当前 Python 环境中生成 ph 命令，无需安装脚本、sudo 或手工创建全局启动器。使用前激活对应环境；也可用 python -m phonon_kit.cli --version 确认正在调用该环境中的版本。

发布包名为 dpa-phonon；GitHub 仓库、Python 导入名 phonon_kit 和现有数据路径 保持不变。如果当前环境安装过旧包 phonon-kit，请先运行 python -m pip uninstall phonon-kit，再安装新包，避免两者共用文件。

本地开发安装：

git clone https://github.com/moliyes/phonon-kit.git
cd phonon-kit
python -m pip install -e ".[test]"
python -m pytest -m "not gpu and not integration"

需要 DeepMD 推理时，请在已经配置好兼容 DeepMD、Torch 和所需计算设备的环境中 安装本工具。它们不作为本包的自动安装依赖；VASP 及其授权和 POTCAR 也需自行准备。 Phonopy、Phono3py、ASE、SeeK-path、spglib、Matplotlib 和 DPDispatcher 会作为 Python 依赖安装。安装成功不代表 GPU 推理或远程 VASP 环境已就绪。 requirements-verified.txt 记录了本机完整验收时使用的依赖版本；它不负责安装 DeepMD/Torch。

包内只携带可重新冻结的 DPA4 checkpoint dpa4_0704.pt，不再分发机器相关的 .pt2。安装后建议在实际计算使用的 DeepMD 环境中运行：

ph model freeze

它会把本机冻结结果写入 ~/.cache/phonon-kit/models/dpa4_0704.pt2。 builtin:dpa4 会优先使用这个 .pt2；若尚未冻结，则自动回退到包内 .pt。 迁移到另一台机器后应重新执行冻结与 ph validate。

2. 最快用法

ph init sio2_case
cd sio2_case
ph validate config.yaml
ph run config.yaml
ph status config.yaml

ph init 会提供一个 SiO₂ 示例结构和使用内置 DPA4 的配置。默认不启用 VASP， 所以只要 GPU/DeepMD 可用即可运行。

三阶声子先预估任务量，再启动：

ph anh init sio2_anh
cd sio2_anh
ph anh plan anh.yaml
ph anh run anh.yaml
ph anh status anh.yaml

系统三阶位移数可能达到数千，务必先执行 plan。

运行产生：

runs/sio2-001/
├── inputs/                 # 本次运行的结构、模型、VASP 和调度配置快照
├── config.resolved.yaml
├── state.json
├── work/
│   ├── canonical/
│   ├── displacements/
│   ├── relaxation/
│   └── methods/
├── results/
│   ├── dpa4/
│   ├── dft/
│   └── comparison/
└── logs/

只需要长期保存 config.yaml、inputs/ 和所需的 runs/*/results/；完整复现或 续跑时应保留整个 run 目录。

3. YAML 说明

路径均相对 config.yaml 解析。每份 YAML 对应一个结构，但可以同时定义多个 DPA 模型和一个 VASP 参考。

当前配置格式全部字段、默认值、单位和组合限制见 config.yaml 参数说明。

声子参数

phonon:
  supercell: [2, 2, 2]          # 有限位移超胞
  displacement_angstrom: 0.01   # 位移幅度，Å
  displacement_plusminus: auto  # 可设 true，强制生成正负位移
  displacement_diagonal: true   # false 时只使用 x/y/z 轴向位移
  primitive: auto
  symmetry_tolerance: 1.0e-5
  band:
    path: auto                   # SeeK-path 自动路径
    points_per_segment: 101
  mesh: [30, 30, 30]            # DOS 与热力学 q 网格
  thermal:
    temperature_min_k: 0
    temperature_max_k: 1000
    temperature_step_k: 10
    imaginary_policy: exclude
    significant_imaginary_thz: -0.1

所有方法复用同一个 phonopy_disp.yaml 和同一条 q 路径。更改超胞、位移、结构、 模型或模板后，配置指纹随之变化，不会把旧力数组混进新任务。

复现已有基准时可将 primitive 设为 P 来保留输入晶胞，并把 band.path 写成显式约化 q 点列表；这可避免自动约胞或自动选路改变比较口径。

DPA3/DPA4

methods:
  dpa4:
    type: deepmd
    model: builtin:dpa4
    device: cuda:0

  dpa3:
    type: deepmd
    model: inputs/models/my_dpa3.pth
    device: cuda:0
    head: null

支持 DeepMD 可加载的 .pt2、.pt、.pth、.pb。ph validate 会实际计算 输入结构的一次能量、力和应力，并检查模型 type map 是否覆盖全部元素。模型能 否运行由真实推理决定，不依赖文件名判断 DPA3/DPA4。

每个位移保存在独立 checkpoints/disp-xxxx.npz。中断后再次运行：

ph resume config.yaml
ph resume runs/sio2-001     # 案例输入修改后，精确恢复指定运行

只会补算缺失或损坏的位移。

可选 DPA 弛豫

relaxation:
  enabled: true
  method: dpa4
  variable_cell: true
  pressure_gpa: 0.0
  fmax_ev_angstrom: 0.01
  max_steps: 1000
  trajectory_interval: 10

使用 FrechetCellFilter + LBFGS。弛豫模型必须是 methods 中启用的 DeepMD 方法。初始帧、每 10 步及最终帧写入 relax.traj；未收敛时不生成声子位移。 所有 DPA/DFT 方法共享同一个弛豫末态，便于严格比较。

4. VASP 与 DPDispatcher

把 INCAR、KPOINTS、POTCAR 放在一个模板目录。软件不会生成或分发 POTCAR。推荐的 INCAR 至少包含：

PREC = Accurate
IBRION = -1
NSW = 0
EDIFF = 1E-8
LREAL = .FALSE.

在 YAML 增加：

  dft:
    type: vasp
    template_dir: inputs/vasp
    executor:
      type: dpdispatcher
      machine: inputs/dispatcher/machine.json
      resources: inputs/dispatcher/resources.json
      command: "source /opt/intel/oneapi/setvars.sh && mpirun -n 16 vasp_std"
      clean_remote_after_success: false

可从 ph init 生成的 .example 文件复制并填写 DPDispatcher 配置。凭据文件、 POTCAR 和 runs 默认被 .gitignore 排除。

ph run config.yaml          # DPA 算完；VASP 提交后立即返回
ph status config.yaml
ph resume config.yaml       # 当前案例输入未改变时，查找匹配运行
ph resume runs/sio2-001     # 推荐：精确恢复指定运行
ph resume runs/sio2-001/config.resolved.yaml
ph resume runs/sio2-001 --wait

每个 VASP 位移目录都保存 atom-map.json。程序用 Phonopy 官方 VASP parser 从 vasprun.xml 读取力，再显式恢复成规范 Phonopy 原子顺序。缺失或截断的 XML 不会被当成成功结果。若你用其他方式提交，只需把 vasprun.xml 放回对应 work/methods/dft/jobs/disp-xxxx/，然后运行 ph collect config.yaml。

5. 输出与物理含义

每个完成的方法自动生成：

• forces.npy、可用时的 energies.npy
• FORCE_SETS、force_constants.hdf5、phonopy_params.yaml
• band.yaml、total_dos.dat、thermal_properties.yaml/csv
• phonon_band.png、phonon_band_dos.png、thermal_properties.png
• summary.json

thermal_properties.csv 同时给出 Phonopy 摩尔单位和 eV/atom。自由能是谐振动 自由能，包含零点能，不包含结构静态能、电子自由能或 PV 项。

负频率按 Phonopy cutoff_frequency=0 排除。若存在低于 significant_imaginary_thz 的模式，图和 summary 会标记 thermodynamic_stability: false；此时自由能只适合作诊断，不能作为严格相稳定 结论。

当 DFT 和至少一个 DPA 都完成时，results/comparison/ 自动生成：

• metrics.csv：力 MAE/RMSE、频率 MAE/RMSE、最低频率
• phonon_band_compare.png
• force_comparison.png
• frequency_error.png

6. 运行版本与恢复

• 第一次运行创建 name-001。
• 配置相同且任务未完成：ph run 自动恢复。
• 配置相同且任务已完成：返回原结果，不重复计算。
• 已完成后修改配置：自动创建 name-002。
• 未完成时修改配置：拒绝混用；用具体运行目录恢复，或加 --new 新建版本。

从 0.2.1 开始，每个新运行会把实际使用的结构、模型、VASP 模板和 DPDispatcher 配置复制到运行内 inputs/，config.resolved.yaml 只引用这份 快照。之后修改案例级 config.yaml 或 inputs/ 不会改变已有运行。恢复任务时 优先传具体运行目录；collect 和 plot 也接受运行目录。调度快照可能包含凭据， 请勿上传 runs/。

状态文件采用原子写入。失败详情保存在 state.json 和 logs/，软件不会制造 假的声子结果来掩盖失败。

独立执行 ph validate 的推理日志保存在案例目录的 .phonon-kit/validation/logs/，该目录默认被 Git 忽略。

7. 多相 QHA 与 P–T 相图

QHA 使用独立配置，不会改变前述单结构声子流程。快速创建三个 SiO₂ 晶相案例：

ph qha init sio2_qha --phases quartz coesite stishovite
cd sio2_qha
# 替换 inputs/phases/*/POSCAR
ph qha plan qha.yaml
ph qha validate qha.yaml
ph qha run qha.yaml
ph qha status qha.yaml

核心流程是每个方法、每个相分别执行多个固定体积点：

固定体积优化原子和晶胞形状
→ 静态 U(V)
→ 每个体积的有限位移声子
→ Fvib(V,T)
→ G(P,T)
→ 多相最低 Gibbs 能比较

DPA 使用 FrechetCellFilter(constant_volume=True)；VASP 使用三套模板： volume_relax 必须为 ISIF=4，static 和 phonon 必须为静态计算。程序不会 自动修改 INCAR，也不会生成 POTCAR。

ph qha run qha.yaml --only dpa4
ph qha run qha.yaml --only dft --new
ph qha resume qha.yaml
ph qha resume qha.yaml --wait
ph qha resume runs/sio2_qha-001
ph qha plot qha.yaml

不同晶相的 primitive cell 可能含不同数量的原子。程序先按 primitive cell 完成 Phonopy-QHA，再统一换算成 eV/最简化学式单元 比较。体积范围不足的 P–T 网格 点不会外推成稳定相，而是在图中显示灰色无数据区域。

若出现显著虚频，负频模式仍按 cutoff_frequency=0 排除并继续分析，但终端、 CSV、JSON 和图片都会标记 thermodynamic_stability=false。这类相图只能视为诊断 结果。

完整字段、VASP 模板、目录结构和结果含义见 QHA 配置与使用说明。

8. 三阶非谐声子与 RTA 热导率

三阶工作流不弛豫结构，输入应已经可靠弛豫。所有模型共享相同结构、系统位移和 q 网格，因此适合比较预训练与微调模型带来的变化：

POSCAR → 系统有限位移 → DeepMD 力 → fc2/fc3
       → 三声子散射 gamma → lifetime → RTA kappa(T)

默认 fc2 和 fc3 使用同一超胞及位移幅度；若二阶相互作用需要更长范围，可以设置 独立的 fc2_supercell。此时还可用 fc2_displacement_angstrom 单独指定 fc2 位移幅度，并用 fc2_is_diagonal 控制是否允许非轴向 fc2 位移；不设置则沿用 fc3 的 displacement_angstrom。subtract_residual_forces 默认关闭，与普通声子流程的原始力口径一致。极性体系可通过 structure.born_file 提供 Phonopy BORN 文件启用 NAC。

ph anh run anh.yaml              # 相同未完成配置会自动续算
ph anh run runs/sio2_anh-001 # 案例输入改变后精确恢复
ph anh plot runs/sio2_anh-001

每个位移力和每个不可约 q 点的散射率都有 checkpoint。主要结果位于 results/<method>/：fc2.hdf5、fc3.hdf5、kappa.hdf5、热导率/寿命 CSV、 三张 PNG 和 summary.json。gamma 是半线宽，linewidth=2*gamma，寿命为 1/(4*pi*gamma) ps；非正 gamma 对应 NaN 寿命。

明显虚频默认不会阻断计算，但图表和摘要会标记为诊断结果。三阶首版只计算纯 三声子本征 RTA 热导率，不含同位素、边界、电子或四声子散射。超胞、位移幅度和 q 网格都必须做收敛检查。完整字段见 三阶配置说明。

9. 常见问题

ph validate 提示 .pt2 无法加载：冻结模型依赖生成它的 GPU、Torch/DeepMD 构建和 CUDA。删除或移走 ~/.cache/phonon-kit/models/dpa4_0704.pt2，确认命令 使用正确的 DeepMD Python，然后执行 ph model freeze --force。如果没有本机 .pt2，builtin:dpa4 会回退到包内 .pt。

VASP 一直显示 waiting：检查每个 disp-xxxx/vasprun.xml 是否完整，而不仅是 OUTCAR 是否存在，然后执行 ph resume 或 ph collect。

自动高对称路径失败：通常是输入结构晶胞或对称性异常。先确保结构已弛豫、晶胞 非奇异，并适当调整 symmetry_tolerance。

自由能有警告：查看 summary.json 的最低频率、显著虚频比例和积分模式比例。

QHA 相图出现灰色区域：至少一个相在对应 P–T 点的拟合平衡体积超出采样体积 范围，或 EOS 无效。查看每相的 volume_points.csv 和 qha_grid.csv，扩大压缩侧 或膨胀侧体积范围后使用 --new 重新计算。

三阶热导率异常大或不平滑：先检查显著虚频、输入是否充分弛豫、fc2/fc3 超胞和 q 网格是否收敛；有限模型比较不能替代这些收敛性检查。

10. Hermes Agent Skill

项目在 skills/materials-science/phonon-kit/ 内提供可版本化的 Hermes Skill， 用于配置、运行和诊断普通声子、三阶声子与多相 QHA 工作流。推荐从项目目录直接加载，避免 把 Skill 复制到用户目录后产生两份不同版本。

在 Hermes config.yaml 中保留已有配置并加入：

skills:
  external_dirs:
    - /path/to/phonon-kit/skills
  config:
    phonon_kit:
      project_root: /path/to/phonon-kit

如果 external_dirs 或 skills.config 已存在，应在原列表和映射中追加，而不是 覆盖。新机器只需把两个路径换成实际项目目录，然后新建 Hermes 会话或执行 /reload-skills。可用下面的命令确认发现情况：

hermes skills list
hermes config get skills --json

显式调用示例：/phonon-kit 检查这个 QHA 运行的体积覆盖和虚频警告。自然语言 提及 Phonopy/Phono3py、DeepMD/VASP 声子、热导率、寿命、QHA 或 P–T 相图时也可自动触发。 Skill 不会因状态检查而擅自执行 run、resume、DFT 提交或模型推理。

11. 构建与发布

在独立的 Python 3.11+ 环境中构建标准 wheel 和源码包：

python -m pip install build twine
python -m build --outdir dist-release
python -m twine check dist-release/dpa_phonon-0.4.0*

发布前，在干净环境中安装 wheel，检查依赖与命令，再测试源码包安装：

python -m pip install dist-release/dpa_phonon-0.4.0-py3-none-any.whl
python -m pip check
ph --version
ph --help

PyPI 发布需要维护者自己的账号和发布授权。完成安装与模型验证后，在本机终端 使用 Twine 上传本次版本的两个文件（API Token 仅在终端认证提示中输入）：

python -m twine upload dist-release/dpa_phonon-0.4.0-py3-none-any.whl dist-release/dpa_phonon-0.4.0.tar.gz

上传成功后，用户才可使用 python -m pip install dpa-phonon==0.4.0。 后续发布需更新版本号，并使用对应版本的文件名和 Git 标签。