Metadata-Version: 2.4
Name: dpa-phonon
Version: 0.4.0
Summary: Phonon and thermal-property workflows powered by DPA models, with VASP support
Author: phonon-kit contributors
License-Expression: MIT
Project-URL: Repository, https://github.com/moliyes/phonon-kit
Project-URL: Issues, https://github.com/moliyes/phonon-kit/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: ase>=3.26
Requires-Dist: dpdispatcher<2,>=1.0
Requires-Dist: h5py>=3.11
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: phonopy==4.4.0
Requires-Dist: phono3py==4.4.0
Requires-Dist: phonors==0.3.0
Requires-Dist: PyYAML>=6
Requires-Dist: seekpath>=2.1
Requires-Dist: spglib>=2.4
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-timeout>=2; extra == "test"
Dynamic: license-file

# 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 后可直接安装：

```bash
python -m pip install dpa-phonon
```

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

```bash
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`，再安装新包，避免两者共用文件。

本地开发安装：

```bash
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 环境中运行：

```bash
ph model freeze
```

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

## 2. 最快用法

```bash
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 可用即可运行。

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

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

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

运行产生：

```text
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 参数说明](docs/config-reference.zh-CN.md)。

### 声子参数

```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

```yaml
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`。中断后再次运行：

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

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

### 可选 DPA 弛豫

```yaml
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 至少包含：

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

在 YAML 增加：

```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` 排除。

```bash
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₂ 晶相案例：

```bash
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
```

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

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

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

```bash
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 配置与使用说明](docs/qha-config-reference.zh-CN.md)。

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

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

```text
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。

```bash
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 网格都必须做收敛检查。完整字段见
[三阶配置说明](docs/anh-config-reference.zh-CN.md)。

## 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` 中保留已有配置并加入：

```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`。可用下面的命令确认发现情况：

```bash
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 和源码包：

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

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

```bash
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 仅在终端认证提示中输入）：

```bash
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 标签。
