147 lines
6.4 KiB
Markdown
147 lines
6.4 KiB
Markdown
---
|
||
name: pymatgen
|
||
description: 无机材料计算工具(晶体结构 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`
|
||
|
||
## 准备
|
||
|
||
```python
|
||
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**:
|
||
|
||
```python
|
||
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) 衍射"
|
||
|
||
```python
|
||
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. 给定结构问对称性
|
||
|
||
```python
|
||
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. 凝胶 / 水化产物相图稳定性
|
||
|
||
```python
|
||
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 输入)
|
||
|
||
```python
|
||
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()` 自动读。
|