zcdsj
/
zcbot
5
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
zcbot/skills/pymatgen/SKILL.md

6.4 KiB
Raw Blame History

name description
pymatgen 无机材料计算工具(晶体结构 I/O、XRD 模拟、相图、对称性、Materials Project 查询)。✅ 触发:用户问水泥熟料相 / 玻璃陶瓷物相 / 耐火砖矿物相、XRD 谱图反演与正向模拟、晶格参数、空间群、相稳定性、查 Materials Project 数据。⛔ 不触发:用户只问材料宏观性能(强度/导热),不涉及晶体结构;或属于有机分子/药物(那是 RDKit 范畴)。

Pymatgen

无机材料计算的核心库,服务建材院的水泥 / 混凝土 / 玻璃 / 陶瓷 / 耐火材料场景。底层用 pymatgen 官方 API,本 skill 提供两个轻量 helper:CEMENT_PHASES 常量(中文相名→化学式映射)和 mp_rester()(从 env 拿 MP_API_KEY)。

⚠️ 2026-05-29 限制:mp_rester() 及一切 Materials Project 联网查询在 sandbox 下不可用 —— run_python 安全过滤器拦 MP_API_KEY env,配了也读不到(等 credential broker)。离线全部正常:用户给 .cif / POSCAR → Structure.from_file() / SpacegroupAnalyzer / XRDCalculator(对已有 Structure)/ CEMENT_PHASES 查表 / 格式转换 / MPRelaxSet。要 mp 拿结构 → 让用户从 https://materialsproject.org 下个 CIF 丢 task 目录;不要脑补晶格 / 原子坐标。

何时用

  • 用户给晶体结构文件(.cif / POSCAR / .xyz)要分析
  • 要正向算 XRD pattern 跟实测谱对比
  • 要查某矿物相的空间群 / 晶格参数 / 配位环境
  • 要做凝胶相 / 水化产物的相图 / 稳定性分析
  • 要从 Materials Project 拉某化合物的已知结构 / 性质
  • 写 VASP / Gaussian / Quantum ESPRESSO 输入文件

何时不用

  • 用户只问宏观性能(28d 抗压、导热系数、热膨胀)→ 走 stats_ml(回归建模)
  • 用户问有机外加剂分子结构 → 走 RDKit(本仓库未集成)
  • 用户只要画图,没有晶体计算需求 → 走 plot_pub

准备

from skills.pymatgen.materials import CEMENT_PHASES, mp_rester
from pymatgen.core import Structure, Lattice, Molecule
from pymatgen.analysis.diffraction.xrd import XRDCalculator
from pymatgen.symmetry.analyzer import SpacegroupAnalyzer
from pymatgen.analysis.phase_diagram import PhaseDiagram, PDEntry

(import 路径走 run_python 注入的 PYTHONPATH,直接写)

关键:中文相名 → 化学式

CEMENT_PHASES dict 收了水泥 / 陶瓷 / 耐火 / 玻璃常见相的中英文 ↔ 化学式映射(见 materials.py)。用户用中文报相名时,先查这张表转化学式再喂 pymatgen / Materials Project:

用户原话 不要这样 这样
C3S Structure.from_file("C3S") 先 CEMENT_PHASES["C3S"] → "Ca3SiO5",再走 mp 查或自己拼
钙矾石(AFt) mp 直接搜 "AFt" CEMENT_PHASES["钙矾石"] → "Ca6Al2(SO4)3(OH)12·26H2O"
莫来石 mp 直接搜 "mullite" CEMENT_PHASES["莫来石"] → "Al6Si2O13"
方镁石 直接搜 "magnesite"(错,那是菱镁矿) CEMENT_PHASES["方镁石"] → "MgO"

表里没有的相,先英文学名 → 化学式后再喂,不要直接把中文丢给 mp。

Materials Project 接入

API key 走 env:MP_API_KEY(申请:https://materialsproject.org/api)。必须用 context manager:

with mp_rester() as mpr:  # 自动从 env 拿 key
    docs = mpr.materials.summary.search(
        formula="Ca3SiO5",
        fields=["material_id", "formula_pretty", "symmetry", "energy_above_hull"],
    )
    for d in docs[:5]:
        print(d.material_id, d.formula_pretty, d.symmetry.symbol, d.energy_above_hull)

MP_API_KEY 没配 → mp_rester() 抛 RuntimeError("MP_API_KEY not set in env..."),告诉用户去配,不要继续。

典型工作流

A. 实测 XRD 比对(谁是这个峰)

  1. 用户给疑似相清单(中文 / 英文 / 简写都行)
  2. 各相分别:CEMENT_PHASES 查化学式 → mp_rester() 拿 Structure → XRDCalculator().get_pattern(structure) 算理论谱
  3. 把各相理论谱跟实测谱(用户给的 xy 数据)叠图(走 plot_pub)
  4. 报"x° 这个峰最可能是 C3S 的 (h k l) 衍射"
from pymatgen.analysis.diffraction.xrd import XRDCalculator

xrd = XRDCalculator(wavelength="CuKa")  # 默认 Cu Kα
with mp_rester() as mpr:
    docs = mpr.materials.summary.search(formula="Ca3SiO5", fields=["material_id"])
    struct = mpr.get_structure_by_material_id(docs[0].material_id)
pattern = xrd.get_pattern(struct, two_theta_range=(5, 80))
# pattern.x = 2θ 列表, pattern.y = 强度, pattern.hkls = (h,k,l) 列表

B. 给定结构问对称性

from pymatgen.core import Structure
from pymatgen.symmetry.analyzer import SpacegroupAnalyzer

struct = Structure.from_file("path/to/sample.cif")
sga = SpacegroupAnalyzer(struct)
print(sga.get_space_group_symbol())   # 例 "P21/c"
print(sga.get_space_group_number())   # 例 14
print(sga.get_crystal_system())       # 例 "monoclinic"
prim = sga.get_primitive_standard_structure()  # 简约胞

C. 凝胶 / 水化产物相图稳定性

from pymatgen.analysis.phase_diagram import PhaseDiagram

with mp_rester() as mpr:
    entries = mpr.get_entries_in_chemsys(["Ca", "Si", "O", "H"])
pd = PhaseDiagram(entries)
# pd.get_decomp_and_e_above_hull(some_entry) → 分解路径 + 能量

D. 格式转换(给计算所做 VASP 输入)

struct.to(filename="POSCAR")  # 自动按后缀写
struct.to(filename="output.cif")

反模式

  • 用户报中文相名(C3S / 钙矾石 / 莫来石)直接喂 mp / pymatgen,不查 CEMENT_PHASES —— mp 不认中文,简写也不认
  • MPRester 不走 context manager(mpr = MPRester(); ...) —— 连接泄漏
  • 手写 CIF parser → 一律 Structure.from_file()
  • 不做 SpacegroupAnalyzer.get_primitive_standard_structure() 直接拿原胞做对称性比对(原胞可能是超胞,对称性少看出来)
  • 大 cutoff 邻居搜索(get_neighbors(r=20))—— 性能差,先 r=5 试
  • 编造 material_id / 化学式 —— mp 查不到就告诉用户"库里没收录",不要凭训练数据脑补
  • 自己写 INCAR(VASP 输入)—— 用 MPRelaxSet / MPStaticSet 拿 mp 验证过的参数
  • 把 pymatgen 算的理论 XRD 当实验值 —— 永远说清是"理论 pattern",实测有择优取向 / 仪器展宽差异

依赖

requirements.txt 加:

pymatgen>=2024.0
mp-api>=0.41.0

装:.venv/Scripts/pip install pymatgen mp-api

env

MP_API_KEY=your_key_from_materialsproject_org

写到 .env(项目根)即可,mp_rester() 自动读。