py4vasp公开方法：从文件到数据对象

计算结束后，先确认要读哪一类结果，再选择对应方法。下载方法表与实算示例，包含py4vasp0.11.3的39类quantity、101种不同方法签名，以及真实Si能带和20帧短MD读取数据。

这些签名包括共享的读取、导出和构造方法，不等于101种独立物性。各quantity的物性用途与文件前提见完整quantity索引；本篇补充终端里怎样实际调用它们。

1 先查询方法，不要盲目全调用#

mkdir py4vasp-API
python3 -m zipfile -e py4vasp-API-*.zip py4vasp-API
cd py4vasp-API
module load py4vasp/0.11.3
python api.py
python api.py band

第一条查询列出39个名称，第二条列出band的方法、参数和使用前提。也可查询：

python api.py density
python api.py structure
python api.py electron_phonon.transport

本环境使用Python3.11。示例HDF为本站实际VASP结果的读取副本，已移除赝势组，保留科学数组原值；不要把它当作VASP续算文件。

2 最常用的入口是from_path#

python - <<'PYCODE'
import py4vasp
c = py4vasp.Calculation.from_path('sample-band')
print(c.band.read().keys())
print(c.structure.number_atoms())
print(c.band.selections())
PYCODE

从目录构造Calculation后，程序按quantity寻找相应HDF。能带、能量等通常来自vaspout.h5；密度等还可能需要同目录的vaspwave.h5。read()或to_dict()取数据，selections()查询这个实际文件能选择什么。

不要因为某个方法存在就认定文件里有相应数据。缺少的电子声子实例、未输出的密度或没有运行过的响应，不能当成数值0。

3 指定文件与使用已有raw对象#

python - <<'PYCODE'
import py4vasp
c = py4vasp.Calculation.from_path('sample-band')
band = c.band.from_file('sample-band/vaspout.h5')
print(band.read()['bands'].shape)
with py4vasp.raw.access('band', path='sample-band') as data:
    same_data = c.band.from_data(data)
    print(same_data.read()['bands'].shape)
PYCODE

from_file明确指定单个文件；from_data适合把已经读入的真实raw数据交给同类方法，文件上下文关闭前先提取需要的数组。一般客户直接用Calculation.from_path即可，不需要手工构造raw对象。

4 结构、路径与实例筛选#

python - <<'PYCODE'
import py4vasp
c = py4vasp.Calculation.from_path('sample-band')
print(c.structure.volume())
print(c.structure.to_ase())
points = c.kpoint.read()['coordinates']
print(c.kpoint.path_indices(points[0], points[19]))
PYCODE

path_indices的起终点是两个三维k坐标，不是两个整数索引；当前方法寻找共线k点，可能包含路径边界的重复点，需要限定单条线段时再按路径范围筛选。旧式POSCAR若没有元素名，from_POSCAR需提供elements；推荐使用带元素行的新式文件。

电子声子容器先查询selections()，再按真实元数据选择。例如已有相应输运结果时：

c = py4vasp.Calculation.from_path('自己的输运计算目录')
print(c.electron_phonon.transport.selections())
selected = c.electron_phonon.transport.select('scattering_approx=CRTA')
print(len(selected))

本站已有CRTA例子该条件返回2个实例。不要拿不存在的nbands_sum条件筛选后，把空列表解释成零电导。本版本的实例读取器会新建对象，index(obj[0])可能因对象身份不匹配抛ValueError；按物理条件选实例优先用select。

5 可视化方法的前提#

方法表完整保留这些条件，没有把依赖缺失或未计算字段写成已支持。能带自旋纹理和磁性场的实际调用见自旋矢量例子，数据导出见下一篇。