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

# Pymatgen

无机材料计算的核心库,服务建材院的水泥 / 混凝土 / 玻璃 / 陶瓷 / 耐火材料场景。离线计算在 sandbox 里用 pymatgen 官方 API;联网查 Materials Project 走 host-side tool。**本 skill 提供一个轻量 helper**:`CEMENT_PHASES` 常量(中文相名→化学式映射)。

> ⚠️ **配置条件**:只有宿主后端配置了 `MP_API_KEY` 时,`mp_search_summary` / `mp_get_structure` / `mp_get_entries` 才会出现在可用工具列表里。没有这些 tool 时,Materials Project 联网查询不可用;离线全部正常:用户给 `.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
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 接入(host-side tools)

API key 只在宿主后端读取,不要在 `run_python` 里读 env。可用 tool:

- `mp_search_summary(formula?, material_ids?, elements?, fields?, limit=10)` —— 查 summary,返回裁剪 JSON
- `mp_get_structure(material_id, filename?)` —— 把结构保存到 task_dir `materials/*.cif`,再用 `Structure.from_file()` 离线计算
- `mp_get_entries(elements, filename?, limit=200)` —— 把 chemsys entries 保存到 task_dir `materials/*.json`

`MP_API_KEY` 没配 → 上述 tool 不会出现,告诉用户配置或手动从 Materials Project 下载 CIF。

## 典型工作流

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

1. 用户给疑似相清单(中文 / 英文 / 简写都行)
2. 各相分别:`CEMENT_PHASES` 查化学式 → `mp_search_summary(formula=...)` 找 material_id → `mp_get_structure(material_id=...)` 保存 CIF → `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α
# 先用 mp_search_summary / mp_get_structure tool 保存 CIF,再:
struct = Structure.from_file("materials/mp-xxxx.cif")
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. 凝胶 / 水化产物相图稳定性

先用 `mp_get_entries(elements=["Ca", "Si", "O", "H"])` 保存 JSON。第一版 host tool 的 entries JSON 主要用于审阅 / 归档;若要直接构造 `PhaseDiagram`,优先使用用户提供的本地 entry 数据或后续补一个专门的 host-side 相图 helper。不要在 sandbox 里绕过 tool 直接连 MP。

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

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

## 反模式

- 用户报中文相名(C3S / 钙矾石 / 莫来石)直接喂 mp / pymatgen,不查 `CEMENT_PHASES` —— mp 不认中文,简写也不认
- 在 `run_python` 里直接用 `MPRester` / 读 `MP_API_KEY` —— key 不进 sandbox,联网查询走 host-side tool
- 手写 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
```

配置后重启 web,`mp_*` tools 才会注册。sandbox / `run_python` 不读取这个 key。