MatSimPy：面向高通量材料计算的 Python 框架

---

MatSimPy：材料建模模拟分析 Python 库

MatSimPy (Materials Simulation in Python) 是一个面向材料模拟的 Python 库，结合了 ASE 的轻量与直观 API 和 pymatgen 的体系化数据模型，在此基础上引入不可变对象设计与严格的坐标语义，构建更可靠的计算工作流。

当前版本：v0.3.0（核心模块稳定）

---

🚀 核心特性

🧱 数据模型

MatSimPy 提供完整的材料建模基础对象：

• Crystal, Molecule, Structure
• Lattice, Composition
• Site, Element

设计目标：简洁 + 一致 + 可扩展

---

🔒 不可变设计（Immutable-by-default）

所有“修改操作”都会返回新对象，而不是原地修改：

doped = crystal.add_atom('H', [0.1, 0, 0])

优势：

• 更安全（避免副作用）
• 易缓存（适合高通量）
• 可链式调用（pipeline-friendly）

---

📐 坐标系统清晰

• Structure.positions → 始终为 笛卡尔坐标

• Crystal 支持：

  • frac_positions（分数坐标）
  • cart_positions（笛卡尔坐标）

👉 避免常见坐标混乱问题

---

🏗️ 构建器（Builders）

支持快速生成复杂结构：

• 晶体：FCC / BCC / Diamond
• 表面：slab
• 缺陷：vacancy / interstitial
• 分子：四面体结构
• 纳米结构：碳纳米管

from matsimpy.builders import from_prototype

fcc_cu = from_prototype('fcc', 'Cu', 3.61)

---

🔄 结构变换（Transformations）

支持多种变换：

• 几何：平移 / 旋转
• 晶格：应变 / 缩放
• 化学：替换元素
• 结构：超胞生成

from matsimpy.transformation import apply_strain

strained = apply_strain(crystal, [0.05, 0, 0])

---

⚡ 高通量计算工具

提供三大核心工具：

1️⃣ Pipeline

pipeline = TransformationPipeline("strain_study")
pipeline.add_step(make_supercell, scaling_matrix=[2,2,2])
pipeline.add_step(apply_strain, strain_matrix=[[0.01,0,0],[0,0,0],[0,0,0]])

2️⃣ 参数扫描

sweep = ParameterSweep(...)

3️⃣ 批处理

processor = BatchProcessor(...)

👉 非常适合材料筛选 & 自动化计算

---

🔬 分析功能

• 对称性分析（spglib）
• 分子图（Graph）
• NetworkX 转换
• 配位数 / 邻接矩阵

graph = MoleculeGraph(molecule, cutoff=2.0)
print(graph.is_connected)

---

📦 文件 IO

支持多种格式：

• VASP / CIF / XYZ / PDB / JSON
• 自动识别格式

from matsimpy.io import read, write

write(crystal, 'POSCAR')
crystal = read('POSCAR')

---

⚙️ 计算器（Calculators）

• 经典势（Lennard-Jones）
• 机器学习势（MACE 等）

energy = crystal.get_potential_energy()

---

🗃️ 数据存储

基于 maggma：

storage.store_data(crystal)

支持：

• JSON 持久化
• 查询 / 重建对象

---

🖥️ CLI 工具

matsimpy

提供：

• 结构生成
• 格式转换
• 分析工具

👉 适合非编程用户

---

📦 安装

基础安装

pip install MatSimPy

---

开发模式

git clone https://gitee.com/haidi-hfut/MatSimPy.git
cd MatSimPy
pip install -e .

---

可选功能

pip install -e .[all]

模块包括：

• ml（机器学习）
• io（格式转换）
• analysis（对称性）
• builders（结构生成）

---

⚡ 快速示例

from matsimpy import Crystal, Lattice

crystal = Crystal(
    ['Na', 'Cl'],
    [[0,0,0], [0.5,0.5,0.5]],
    Lattice.cubic(5.64)
)

print(crystal.formula)  # NaCl
print(crystal.volume)

---

📁 项目结构

matsimpy/
├── core/
├── builders/
├── transformation/
├── io/
├── calculator/
├── symmetry/
├── storage/
├── ui/

👉 模块划分清晰，易扩展

---

🧪 测试

pytest
pytest --cov=matsimpy

支持：

• 并行测试
• 覆盖率分析

---

📚 文档

• Sphinx 文档（docs/）
• 示例（examples/）
• API Docstring

---

✨ 总结

MatSimPy 的核心优势：

✔ 不可变设计（非常现代）
✔ 高通量计算友好
✔ API 清晰统一
✔ 覆盖建模 → 计算 → 存储全流程

---

🔗 项目地址

👉 https://gitee.com/haidi-hfut/MatSimPy

---

👨‍💻 作者

Haidi Wang
📧 haidi@hfut.edu.cn

---

📌 未来方向

• 可视化模块
• 更强 ML 集成
• 更丰富 builder

---

如果你熟悉 pymatgen 或 ASE，MatSimPy 会让你感觉非常自然，但更现代、更干净。

🚀 欢迎 Star & 贡献！