py4vasp 数据入口与文件前提
列出0.11.3全部39个公开quantity、源文件、版本和方法，并区分真实数据、元数据与空返回值。
阅读本篇目录
面对VASP的HDF5文件，先确认算过什么，再选择读取接口。py4vasp0.11.3有39个公开quantity；函数存在、能够调用，和文件里已经保存相应物性，是三件不同的事。本篇按安装版本列出入口，并用8份真实结果检查实际内容。
1. 获取数据与选择操作#
unzip py4vasp-quantities-wave151-*.zip -d py4vasp-examples
cd py4vasp-examples
bash run.sh list
后处理模块为 py4vasp/0.11.3，使用独立Python3.11环境；结构和静态图使用 ase/3.29.0 的Python3.11.16、NumPy2.3.5、Matplotlib3.11.2。只需已分配资源内1个CPU，不需要GPU。
bash run.sh 1 # 39个数据入口、版本和文件前提
bash run.sh 2 # 介电、Born、压电和内部应变
bash run.sh 3 # 电子收敛、带隙及CSV
也可以在新解压目录运行 bash run-all.sh，得到 analysis/ 与 figures/。另一份新目录运行 bash analyze.sh，结果写入 analysis-reference/、figures-reference/。这两条命令只处理已经提供的数据，不重新运行VASP。输出目录保护会拒绝覆盖已有结果。
8份输入包含两类实际计算：5份已有VASP6.6.1/P100 HDF5结果（NVHPC25.3、CUDA12.8），以及3份Si/NaCl/ZnS的CPU DFPT结果（vasp/6.6.1-8173m-hdf5，InteloneAPI2024.2、MPI/OpenMP、HDF51.14.6）。新CPU计算采用1个MPI进程×4个OpenMP线程；读取HDF5与计算平台分开，py4vasp本身不替代VASP求解。
2. 先列出实际能读到什么#
bash run.sh 1
head -12 inventory/availability.csv
inventory/QUANTITIES.json包含每个入口的源文件、安装版本声明的最低VASP版本、选择、公开方法签名和本包8份数据的实际结果。availability.csv适合用表格软件查看。
下图区分：实际数据、元数据/选择器、仅投影电荷、仅结构、空结果/零累加器、当前输入缺少目标数据。浅灰色不表示py4vasp没有这个功能，而表示这份计算没有提供所需结果。
3. 39个入口与文件前提#
表中的版本来自当前安装schema；“未单列”表示接口未在这里单列最低版本，不意味着任意旧版VASP都支持。实际文件路径和全部选择见JSON，不只看文件扩展名。
| 入口 | 默认/首个源文件 | 声明最低版本 | 本例与使用前提 |
|---|---|---|---|
band |
vaspout.h5 |
未单列 | 能带及占据；使用实际k点路径或网格，不自动生成新计算。 |
bandgap |
vaspout.h5 |
6.5.0 | 原生带边摘要；需区分采样点上的基本带隙与直接带隙。 |
born_effective_charge |
vaspout.h5 |
6.3.0 | LEPSILON等线性响应产生的Born张量，本包新增3例。 |
current_density |
vaspout.h5 |
6.5.1 | 当前版本选用nmr源；本包只返回结构，没有电流密度网格。 |
density |
vaspwave.h5 |
未单列 | 读取vaspwave.h5中的密度；本包NaCl电荷例有数据。 |
dielectric_function |
vaspout.h5 |
6.3.0 | LOPTICS等得到的频率响应；本包Si光学例有数据。 |
dielectric_tensor |
vaspout.h5 |
6.3.0 | 静态电子与离子响应；本包3个新增DFPT例。 |
dos |
vaspout.h5 |
未单列 | 能量网格及态密度；谱形仍受k点/展宽影响。 |
effective_coulomb |
vaspout.h5 |
6.6.0 | 需要相应有效库仑作用计算数组；普通SCF不能补出。 |
elastic_modulus |
vaspout.h5 |
6.3.0 | 需要完整弹性响应；仅有离子贡献不等于完整弹性模量。 |
electronic_minimization |
vaspout.h5 |
6.5.0 | 电子步能量、变化、残差及收敛标记。 |
energy |
vaspout.h5 |
未单列 | 按类型和离子步读取；自由能、内能等不要混用。 |
force |
vaspout.h5 |
未单列 | 原子力及其离子步切片。 |
force_constant |
vaspout.h5 |
6.3.0 | 振动力常数；本包Gamma DFPT例有数据。 |
internal_strain |
vaspout.h5 |
6.3.0 | 原子位移与应变的能量耦合，单位eV/Å；不是无量纲应变。 |
kpoint |
vaspout.h5 |
未单列 | 所用k点、权重和路径信息。 |
local_moment |
vaspout.h5 |
6.5.0 | 本包非自旋计算只能读取投影电荷，不能据此报告磁矩。 |
nics |
vaspout.h5 |
6.5.0 | 需相应核独立化学位移计算数据。 |
pair_correlation |
vaspout.h5 |
6.4.0 | 本包20步Si轨迹有原生数据，不能当作收敛液体RDF。 |
partial_density |
vaspout.h5 |
6.5.0 | 需选带/选k等部分电荷密度输出，本包未提供。 |
piezoelectric_tensor |
vaspout.h5 |
6.3.0 | 电子与离子压电响应，本包ZnS有非零实例。 |
polarization |
vaspout.h5 |
6.3.0 | 需对应极化数据；本包未把Born张量当作绝对极化。 |
potential |
vaspout.h5 |
6.5.0 | 本包只返回结构，没有势网格，不是零势。 |
projector |
vaspout.h5 |
未单列 | 投影选择器元数据，不是波函数或投影电荷本身。 |
run_info |
vaspout.h5 |
未单列 | 运行元数据；单个标记不能代替目标数组是否存在的检查。 |
stress |
vaspout.h5 |
未单列 | 应力张量与轨迹切片，注意单位与张量约定。 |
structure |
vaspout.h5 |
未单列 | 晶胞、元素、分数坐标和离子步。 |
system |
vaspout.h5 |
未单列 | 体系标识元数据。 |
velocity |
vaspout.h5 |
6.4.0 | 需实际速度数组；元数据标记不保证轨迹速度可读取。 |
workfunction |
vaspout.h5 |
6.5.0 | 需功函数及势参考数据，本包未提供。 |
electron_phonon.bandgap |
vaspout.h5 |
6.5.2 | 需电子-声子带隙数据，普通bandgap不能替代。 |
electron_phonon.chemical_potential |
vaspout.h5 |
6.5.2 | 需电子-声子化学势/温度数据。 |
electron_phonon.self_energy |
vaspout.h5 |
6.5.2 | 本包naccumulators=0，没有已计算的自能。 |
electron_phonon.transport |
vaspout.h5 |
6.5.2 | 本包naccumulators=0，没有已计算的输运系数。 |
exciton.density |
vaspout.h5 |
6.5.0 | 需实际激子密度数据。 |
exciton.eigenvector |
vaspout.h5 |
6.4.0 | 需BSE等产生的激子本征矢。 |
phonon.band |
vaspout.h5 |
6.4.0 | 需实际声子路径数据；Gamma模式不能补出完整色散。 |
phonon.dos |
vaspout.h5 |
6.4.0 | 需声子q网格/DOS输出，不能用六个Gamma频率冒充。 |
phonon.mode |
vaspout.h5 |
6.5.2 | 本包Gamma DFPT模式及本征矢可读取。 |
4. 不要把空返回值理解成零物性#
module load py4vasp/0.11.3
python - <<'PYCODE'
import py4vasp
c = py4vasp.Calculation.from_path("inputs/si-response")
print(c.potential.read().keys())
print(c.electron_phonon.self_energy.read())
print(c.electron_phonon.transport.read())
PYCODE
本例势接口只包含 structure，电子-声子自能/输运返回 naccumulators: 0。它们都不代表“势为零”或“电声耦合为零”，应该回到原计算检查是否产生目标数据。当前版本对某些缺少数组的入口也可能直接返回异常；先查输入前提和HDF5内容，再选择对应教程。
local_moment 在本包非自旋算例中读到的是轨道投影电荷，不是磁矩；run_info 的速度相关标记也不能代替实际 velocity 数组读取。
5. read、选择和导出方法怎样查#
python - <<'PYCODE'
import json
a = json.load(open("inventory/QUANTITIES.json"))
q = next(x for x in a["rows"] if x["name"] == "electronic_minimization")
print(q["sources"])
for method in q["public_methods"]:
print(method["name"], method["signature"])
PYCODE
read()通常得到字典；图形接口与转换方法因quantity而异，不能把某个入口支持的选择字符串直接套给其他入口。比如电子收敛图一次选择 E 或 dE；本版本不接受 E,dE 作为组合图形选择。
NMR电流密度源名是 nmr，调用形式为 c.current_density.read(selection="nmr")，仍须有真实电流数据。目录读取优先用 Calculation.from_path()，它能按quantity寻找不同HDF5文件；强行把全部接口绑定到 vaspout.h5 会漏掉位于 vaspwave.h5 的密度。
6. 按目标继续操作#
- 静态介电与Born电荷：完整CPU DFPT输入与张量提取。
- 压电与内部应变：ZnS非零实例、轴顺序及单位。
- 电子收敛与带隙：OSZICAR、CSV、原生图形与带边对照。
- 既有能带和DOS教程及密度和轨迹教程。
39个入口的完整索引不表示39种物性都已在本包计算。对应API定义参考py4vasp官方calculation目录；本文固定0.11.3，不直接套用后来版本新增的字段。