【工具分享】MolCrysKit：分子晶体与有机-无机杂化晶体的建模工具包

SchrodingersCat

准确的模拟计算离不开恰当的建模。有一大类晶态材料，其结构中包含可辨识的分子或离子片段（如有机小分子、配体、有机阳离子等），这些片段通过共价键维持自身完整性，再经由氢键、配位键、π-π 堆积、范德华力等相互作用组装成周期性晶体。药物晶体、含能材料、有机半导体、金属有机框架（MOF）、杂化钙钛矿等均属此类，大量收录于剑桥晶体学数据库（CSD）及相关结构数据库中。对这类体系做建模时，常常遇到以下问题：

• CIF 含有占据无序，不能直接用于 MD 或 DFT 计算
• X 射线衍射分析不能准确确定氢原子位置，部分结构数据常缺失氢原子坐标，需要手动补全
• 切表面时容易切断共价键，破坏分子完整性，需反复人工调整
• 批量处理 CSD 结构时，每个体系都需手动检查分子识别是否正确
  

过去，上述建模步骤主要依赖 Materials Studio 等 GUI 软件逐一、手动操作，难以脚本化和批量化，还容易出错。为此，我们开发了 MolCrysKit 工具包，基于图论算法自动处理上述问题，MIT 协议开源。

值得一提的是：基于此工具包，也可以通过模型上下文协议（MCP）或者Skill等方式让AI智能体协助分子晶体的建模和材料信息学分析。

核心功能

1. 分子识别
从周期性晶体结构中自动识别完整分子（正确处理跨 cell 边界的情况）。基于图论的键连接判定，不依赖残基标签。


2. Disorder 处理
自动解析 CIF 中的占据无序，生成有序结构。


3. 拓扑保全表面切割
切表面时保证分子完整性。支持指定 Miller 面、层数、真空层厚度，以及自动枚举不同终端。



4. 加氢补全
基于配位几何和 CIF formula moiety 信息自动补氢。支持常见配位构型（四面体、三角锥、弯曲等），可自定义键长规则。



5. QM 簇切割
按配位壳层从晶体中切出球形分子簇，适用于 ONIOM / embedded cluster 计算。支持冻结外壳原子、封端等选项。



安装

1. pip install molcrys-kit

复制代码

需要 Python ≥ 3.10。依赖 ASE、NetworkX 等常用库，会自动安装。

也可以安装GitHub上最新代码：

1. pip install git+https://github.com/SchrodingersCattt/MolCrysKit.git@main

复制代码

快速体验（CLI）

安装后自带mck命令，不写 Python 也能用：

1. # 查看晶体基本信息（分子组成、空间群等）
   
2. mck io info structure.cif
   
3. 
   
4. # 列出晶体中所有独立分子
   
5. mck io molecules structure.cif --json
   
6. 
   
7. # 解 disorder，输出有序结构
   
8. mck operate disorder disordered.cif -o ordered.cif
   
9. 
   
10. # 补氢
    
11. mck operate add-h no_hydrogen.cif -o with_h.cif
    
12. 
    
13. # 切 (001) 表面，3层，15 Å 真空
    
14. mck operate slab crystal.cif -o slab.cif --miller 0 0 1 --layers 3 --vacuum 15.0
    
15. 
    
16. # 切 QM 簇
    
17. mck operate cluster crystal.cif -o cluster.xyz --seed-index 0 --mode bond_shells

复制代码

Python API 示例

1. import molcrys_kit as mck
   
2. 
   
3. # 读取 CIF
   
4. crystal = mck.read_mol_crystal("OCHTET12.cif")
   
5. 
   
6. # 查看分子组成
   
7. for mol in crystal.molecules:
   
8.     print(mol.get_chemical_formula())
   
9. 
   
10. # 切表面
    
11. from molcrys_kit.operations import generate_topological_slab
    
12. slab = generate_topological_slab(crystal, miller_indices=(0, 0, 1), layers=3, vacuum=15.0)
    
13. 
    
14. # 切 QM 簇
    
15. from molcrys_kit.operations import carve_cluster
    
16. cluster = carve_cluster(crystal, seed=[0], mode="bond_shells")

复制代码

链接
GitHub：https://github.com/SchrodingersCattt/MolCrysKit
PyPI：https://pypi.org/project/molcrys-kit/
文档：见 GitHub 仓库 docs 目录


引用
如果在学术工作中使用了 MolCrysKit，请引用：

1. Guo, M.-Y.; Zhang, W.-X. MolCrysKit: A Topology-Aware Toolkit for Bridging Experimental Molecular-Crystal Structures and Simulation-Ready Modeling. J. Chem. Inf. Model. 2026, 66(9), 4999–5007. DOI: 10.1021/acs.jcim.6c00168

复制代码

欢迎试用和反馈！使用中遇到的问题可以直接在 GitHub 提 issue，或者在本帖回复讨论。
如果有特殊的分子晶体处理需求（比如某类 disorder 解析不正确、某个体系切面有问题等），也欢迎提供 CIF 文件，我们会尽快修复。