I/O：读写文件格式¶

读取器将文件转为 Frame，写入器将 Frame 转回文件——所有 I/O 格式都遵循这一模式。如需添加新格式，见开发者指南：I/O 格式。

MolPy 的 I/O 系统分三层：数据（单帧结构）、轨迹（多帧序列）和力场（参数文件）。每层有各自的读写器基类。

数据文件：Frame 进，Frame 出¶

数据读取器读文件返回 Frame，写入器接收 Frame 生成文件。Frame 是通用交换对象——包含原子表、键表、元数据，以及可选盒子（box）。

读取¶

每种格式对应一个工厂函数 mp.io.read_*：

import molpy as mp

frame = mp.io.read_pdb("molecule.pdb")
frame = mp.io.read_gro("system.gro")
frame = mp.io.read_mol2("ligand.mol2")
frame = mp.io.read_lammps_data("system.data", atom_style="full")
frame = mp.io.read_xyz("coords.xyz")
frame = mp.io.read_h5("snapshot.h5")

所有读取器模式相同：传入文件路径，返回 Frame。可选的 frame 参数可填充已有帧，而非创建新帧。

# 填充已有帧（适用于合并元数据）
existing = mp.Frame(timestep=42)
frame = mp.io.read_pdb("molecule.pdb", frame=existing)
print(frame.metadata["timestep"])  # 42

返回的 Frame 通常包含 "atoms" 块（存储坐标），视格式不同还可能包含 "bonds"、"angles" 和 "dihedrals" 块。

frame = mp.io.read_pdb("water.pdb")
print(frame["atoms"].nrows)           # 原子数
print(list(frame["atoms"].keys()))    # ['id', 'element', 'x', 'y', 'z', ...]

写入¶

写入器沿用同样的工厂模式：

mp.io.write_pdb("output.pdb", frame)
mp.io.write_gro("output.gro", frame)
mp.io.write_lammps_data("output.data", frame, atom_style="full")
mp.io.write_h5("output.h5", frame)
mp.io.write_xsf("output.xsf", frame)

对于 LAMMPS，同时写入数据文件和力场系数很常见。write_lammps_system 是便捷封装——等价于依次调用 write_lammps_data 和 write_lammps_forcefield。第一个参数是目录：若不存在则自动创建，两个文件（固定命名为 system.data 和 system.ff）写入该目录下：

paths = mp.io.write_lammps_system("system", frame, ff)
# 创建目录 system/，包含：
#   system/system.data   （拓扑 + 坐标）
#   system/system.ff     （力场系数）
# 并返回 {"data": Path("system/system.data"), "ff": Path("system/system.ff")}

支持的数据格式¶

格式	读	写	说明
PDB	`read_pdb`	`write_pdb`	ATOM/HETATM + CRYST1 + CONECT
GRO	`read_gro`	`write_gro`	GROMACS 结构文件
MOL2	`read_mol2`	—	Tripos MOL2
LAMMPS data	`read_lammps_data`	`write_lammps_data`	需要 `atom_style`
LAMMPS molecule	`read_lammps_molecule`	`write_lammps_molecule`	模板文件
XYZ	`read_xyz`	—	简单坐标格式
XSF	`read_xsf`	`write_xsf`	XCrySDen 格式
HDF5	`read_h5`	`write_h5`	二进制压缩格式
AMBER AC	`read_amber_ac`	—	Antechamber 格式
AMBER inpcrd	`read_amber_inpcrd`	—	AMBER 坐标文件

轨迹文件：惰性 Frame 序列¶

轨迹读取器返回一个可索引、可迭代的帧序列对象。该对象通过内存映射文件和持久化索引来高效处理大规模轨迹。

读取¶

reader = mp.io.read_lammps_trajectory("dump.lammpstrj")

print(reader.n_frames)       # 总帧数
frame_0 = reader[0]          # 按索引随机访问
frame_last = reader[-1]      # 支持负索引
subset = reader[10:20]       # 切片返回 list[Frame]

迭代是惰性的——帧在需要时解析，支持后台预取：

for frame in reader:
    atoms = frame["atoms"]
    # 逐帧处理

使用完毕务必关闭读取器（或用上下文管理器）以释放内存映射文件描述符：

reader.close()

写入¶

轨迹写入器接收帧列表：

mp.io.write_lammps_trajectory("output.lammpstrj", frames, atom_style="full")
mp.io.write_xyz_trajectory("output.xyz", frames)
mp.io.write_h5_trajectory("output.h5", frames)

支持的轨迹格式¶

格式	读	写	说明
LAMMPS dump	`read_lammps_trajectory`	`write_lammps_trajectory`	支持自定义列
XYZ	`read_xyz_trajectory`	`write_xyz_trajectory`	多帧 XYZ
HDF5	`read_h5_trajectory`	`write_h5_trajectory`	二进制压缩，快速

日志文件：模拟运行元数据¶

LAMMPS 日志文件与数据文件和轨迹文件不同：它记录 LAMMPS 每次 run 期间执行的操作，而非原子位置。MolPy 还原了这种结构。解析后的日志包含 LAMMPS 头部信息、runs 元组，以及暂未被专用字段捕获的原始文本。

核心思路：需要 run 级别的诊断信息（热力学输出、循环计时、负载均衡、近邻统计或警告）时，用 read_LAMMPS_log。 热力学表格以 NumPy 兼容的数据类形式存储，下游分析可以直接使用 LAMMPS 的动态列名。

按日志中出现的顺序访问各个 run：

log = mp.io.read_LAMMPS_log("log.lammps")
run = log.runs[0]

print(run.thermo.columns)
print(run.thermo.data["Temp"].mean())
print(run.loop_time.seconds)
print(run.neighbor_statistics.dangerous_builds)

解析器兼容旧版仅热力学代码。LAMMPSLog(path).read() 仍支持 log["stages"]，但新代码建议改用 log.runs。

legacy = mp.io.LAMMPSLog("log.lammps").read()
first_stage = legacy["stages"][0]
print(first_stage["Step"][0])

支持的日志格式¶

格式	读	写	说明
LAMMPS log	`read_LAMMPS_log`	—	返回与 LAMMPS 运行输出对齐的嵌套数据类

力场文件：ForceField 进，ForceField 出¶

力场读取器从参数文件解析出 ForceField 对象；写入器则将 ForceField 对象序列化为指定引擎的格式。

读取¶

ff = mp.io.read_xml_forcefield("oplsaa.xml")
ff = mp.io.read_lammps_forcefield("system.ff")
ff = mp.io.read_top("forcefield.itp")

AMBER prmtop 文件同时包含结构和参数。read_amber 同时返回两者：

frame, ff = mp.io.read_amber("system.prmtop", "system.inpcrd")

写入¶

每个写入器从同一个 ForceField 对象生成特定引擎格式的输出：

from molpy.io.forcefield import LAMMPSForceFieldWriter, XMLForceFieldWriter
from molpy.io.forcefield.top import GromacsForceFieldWriter

# LAMMPS 系数
LAMMPSForceFieldWriter("system.ff", precision=4).write(ff)

# GROMACS .itp
GromacsForceFieldWriter("system.itp", precision=4).write(ff)

# OpenMM XML
XMLForceFieldWriter("system.xml", precision=6).write(ff)

类型过滤¶

LAMMPS 力场文件通常只需包含系统中实际使用的类型。传入类型集合即可过滤输出：

LAMMPSForceFieldWriter("system.ff").write(
    ff,
    atom_types={"CT", "HC", "OH"},
    bond_types={"CT-HC", "CT-OH"},
)

支持的力场格式¶

格式	读	写	说明
OpenMM/OPLS XML	`read_xml_forcefield`	`XMLForceFieldWriter`	主力场格式
LAMMPS coefficients	`read_lammps_forcefield`	`LAMMPSForceFieldWriter`	支持混合样式
GROMACS .itp	`read_top`	`GromacsForceFieldWriter`	拓扑格式
AMBER prmtop	`read_amber`	—	返回 `(Frame, ForceField)`

扩展新格式¶

添加新的数据、轨迹或力场格式，只需继承对应的读写器基类并注册工厂函数。具体流程——DataReader/DataWriter、BaseTrajectoryReader/TrajectoryWriter、ForceFieldWriter 及格式化器注册——详见 开发者指南：I/O 格式。

快速参考¶

我想...	函数
读取 PDB	`mp.io.read_pdb(path)`
写入 LAMMPS data + ff	`mp.io.write_lammps_system(dir, frame, ff)`
读取轨迹	`mp.io.read_lammps_trajectory(path)`
加载 OPLS-AA	`mp.io.read_xml_forcefield("oplsaa.xml")`
读取 AMBER 拓扑	`mp.io.read_amber(prmtop, inpcrd)`
写入过滤后的力场	`LAMMPSForceFieldWriter(path).write(ff, atom_types={...})`
添加新格式	开发者指南：I/O 格式

另请参阅：API 参考：I/O、概念：力场。