MolPy

快速入门展示了一个完整流程；示例画廊收集了一批可直接复制运行的短工作流。

01 · 解析/构建

用文本描述化学结构 ¶

一行 SMILES 或 BigSMILES 就能定义可编辑的结构——无论单个分子还是整条聚合物链。

from molpy.builder import polymer

mol = mp.parser.parse_molecule("CCO")   # 从 SMILES 得到一个分子
peo = polymer("{[<]CCOCC[>]}|10|")      # 或整条链，聚合度 DP = 10

02 · 编辑

逐个原子地重新连接拓扑 ¶

合并结构、创建和断开化学键、移除离去基团——然后在新连接处重新推导出角和二面角。

chain = mon_a.merge(mon_b)                # 合并两个单体
chain.def_bond(anchor_C, port_O)          # 形成新的 C–O 键
chain.del_atom(o_leave, h1, h2)           # 移除离去的水分子
chain = chain.get_topo(gen_angle=True, gen_dihe=True)

03 · 类型化

在数据层面分配类型 ¶

用 SMARTS 匹配把每个原子、键、角和二面角映射到力场参数——导出前就能检查和验证。

ff    = mp.io.read_xml_forcefield("oplsaa.xml")      # 内置 OPLS-AA
typed = mp.typifier.OplsTypifier(ff).typify(chain)

04 · 填充

使用 Packmol 填满周期性盒子 ¶

在目标密度下无碰撞填充，由 Python 驱动 Packmol 来完成。想要纯 Rust 版本？我们的 molpack 填充器尚在测试阶段，欢迎试用。

from molpy.pack import Packmol, Target, InsideBoxConstraint

target = Target(typed.to_frame(), 500, InsideBoxConstraint(length=30.0))
packed = Packmol()([target], seed=42)     # 一个无碰撞的 Frame

05 · 导出

写入你的引擎真正能运行的文件 ¶

每个文件一条命令：同时写出 LAMMPS data 文件和力场系数。GROMACS、PDB 和 HDF5 的写入接口也遵循同样的模式。

packed.box = mp.Box.cubic(30.0)
mp.io.write_lammps_data("system.data", packed, atom_style="full")
mp.io.write_lammps_forcefield("system.ff", ff)

06 · 分析

将轨迹转换为可观测量 ¶

同一份数据直接传给 Rust 后端计算内核——两次调用就能得到近邻搜索和 g® 结果。另有三十多种分析功能可用。

from molpy.compute import NeighborList, RDF

neighbors = NeighborList(cutoff=8.0)(packed)
result    = RDF(n_bins=50, r_max=8.0)(packed, neighbors)   # 整个盒子的 g(r)

一个数据结构，整个生态: 所有 MolCrafts 工具共享同一套 molrs 后端抽象数据结构——molpack、molvis、molmcp 都能直接读取。工具之间不需要转换器，不需要胶水代码。
全面依托 Rust 内核: Frame、Block 以及每个计算算子的底层都是 molrs——一个 Rust 列存储，提供零拷贝 NumPy 视图和 O(N) 链接网格近邻搜索。
为 LLM 智能体打造: molmcp 套件通过 MCP 提供 MolPy 的符号、文档和实时结构——智能体能检查 Frame 并调用真实 API，依据源码而非猜测。
使用其中一块，或全部使用: 解析器、构建器、类型化器、填充器以及 I/O 和计算模块之间只通过显式数据通信——没有隐藏的共享状态。只导入需要的那一层，其余可忽略。
没有任何硬编码: 新的计算算子、I/O 格式、力场风格或类型化器都可以从核心外部注册——内部的目录是开放注册表，而非硬编码列表。
端到端类型化: 公共 API 全都带有完整的类型提示，CI 中用 Astral 的 ty 检查。编辑器会给出真实的签名补全，不会回退到 Any。