dpdata对象接口、混合体系与分子键图

除了程序输出，dpdata还能对接ASE和pymatgen对象、按组成组织训练数据、保留分子键图，以及生成量化输入。本篇将这些用途分开操作，避免“导出一个文件”就丢掉原有的标签或拓扑。

1 下载与准备#

下载格式实例包，保存为dpdata-formats.zip。

python3 -m zipfile -e dpdata-formats.zip .
cd dpdata-formats
bash run.sh

最后一条列出示例名，选中一个再运行，例如bash run.sh qe-cp。脚本调用集群现有Python 3.11环境中的dpdata 1.1.0、NumPy等依赖，只读取、转换数据，不启动原计算程序。需要批作业时可用sbatch job.slurm qe-cp，只申请1个CPU。输出保存在results/。

2 ASE、pymatgen与帧列表#

bash run.sh bridge-ase-structure
bash run.sh bridge-pymatgen-structure
bash run.sh pymatgen-energy-entry
bash run.sh frame-list

import dpdata
si = dpdata.LabeledSystem('data/si-nine', fmt='deepmd/npy')
one = si.sub_system(0)
atoms = one.to('ase/structure')[0]
structure = one.to('pymatgen/structure')[0]
entry = one.to('pymatgen/computedstructureentry')[0]
frames = si.to('list')
print(len(atoms), len(structure), entry.energy, len(frames))

这里Si9是此前集群真实VASP计算的9个双原子构型；entry.energy为当前帧总能，不是每原子能。结构对象与带计算结果的entry用途不同；从结构对象读回System不会自动恢复原能量和原子力。

3 pymatgen分子接口：当前版本读取文件名#

bash run.sh bridge-pymatgen-molecule

mol = dpdata.LabeledSystem('samples/gaussian/methane.gaussianlog', fmt='gaussian/log')
molecule = mol.to('pymatgen/molecule')[0]
molecule.to(filename='methane.xyz', fmt='xyz')
back = dpdata.System('methane.xyz', fmt='pymatgen/molecule')

1.1.0这一读取路径实际调用Molecule.from_file，所以读取端传文件名；不能把写出返回的对象直接塞回读取端。分子写成普通XYZ后只保留元素和坐标，原量化能量与力继续保存在原LabeledSystem。当前这条pymatgen读取路径默认没有设置nopbc，虽然对象来自分子；确认对象确为非周期分子后，应显式设置back.data['nopbc'] = True，再保存训练数据。不能把保护层晶胞解释为真实周期盒子。

4 MOL/SDF：保留键级和形式电荷#

bash optional.sh
bash run.sh bonds-mol
bash run.sh bonds-sdf
bash run.sh bonds-charged-mol

m = dpdata.BondOrderSystem('samples/bond_order/CH3OH.mol', fmt='mol')
print(m.data['bonds'])
print(m.data['formal_charges'])
m.to('mol', 'methanol.mol')

bonds保存原子索引和键级，形式电荷与部分电荷不同，不能把这组整数电荷解释成Bader电荷。甲醇例含6原子、5条键；SDF例子含4个甲烷同拓扑构象，每个5原子、4条键。带电例子CH₃NH₃⁺的形式电荷求和为+1。SDF例子使用甲烷的同拓扑构象；不同分子拓扑不能仅因为同为SDF就强行当成一个构象集合。

optional.sh将固定版本RDKit2025.9.3和py3Dmol2.5.3安装在当前算例目录addons/，使用集群现有NumPy/Pillow依赖；保持公共Python环境。只做不需要这些接口的例子时可跳过。

5 混合组成：CH₄与CH₃#

bash run.sh mixed-deepmd-npy-mixed
bash run.sh mixed-deepmd-hdf5-mixed

other = dpdata.LabeledSystem('samples/gaussian/methane_sub.gaussianlog', fmt='gaussian/log')
ms = dpdata.MultiSystems(mol, other)
ms.to('deepmd/npy/mixed', 'mixed-data')
back = dpdata.MultiSystems.from_file('mixed-data', fmt='deepmd/npy/mixed')
print(len(back))

得到CH₄和CH₃两个组成组。它们的原子数不同，不能拼成规则frames×natoms×3数组而不保留每帧类型与有效原子信息。这里仅演示格式组织；两个上游量化样本不能据此称为充分或一致的生产训练集。

6 生成输入：Gaussian、Psi4与SQM#

bash run.sh structure-gaussian-gjf
bash run.sh psi4-input
bash run.sh sqm-input

mol.to('gaussian/gjf', 'methane.gjf', keywords='force HF/sto-3g', charge=0, multiplicity=1)
mol.to('psi4/inp', 'methane.psi4.in', method='HF', basis='sto-3g')
mol.to('sqm/in', 'sqm.in', qm_theory='PM6')

生成后先打开文件确认元素、坐标、电荷、多重度、方法和基组，再按对应软件教程提交。写入force关键字只是请求将来的计算输出力，不代表现在已经有新标签；也不要把HF示范基组当成所有体系的推荐精度。

7 字符串与三维查看器#

bash run.sh vasp-string
bash run.sh 3dmol-view

text = one.to('vasp/string')
print(text)
viewer = one.to('3dmol')

vasp/string只写出字符串；读取POSCAR文本可以使用io.StringIO(text)和vasp/poscar。3dmol返回py3Dmol查看器，附件会导出results/viewer.html，下载到本机浏览器打开；显示脚本需要相应在线JS资源。它用于观察结构，不生成计算结果、训练标签或量化轨道。

完整方向和别名见全部格式索引。

图表数据与重新绘图#

bash plot.sh

图件保存在plots/，原数值另存于附件reference-data/。直接下载：AMBER-energy.csv、DFTB-NH3-geometry-forces.csv、Gaussian-CH4-trajectory.csv、Si9-reference.csv。