pymatgen

用途

pymatgen 用于对组分（Composition）、分子（Molecule）、周期性结构（Structure）、计算条目、对称性、相图、电子结构以及电子结构计算软件文件进行显式且保留溯源的操作。该技能将每一次解析、转换、对称性指派、变换和数据库结果都视为依赖方法与参数的结果。

主要能力

核心对象：Composition、Element、Lattice、Molecule、Structure，支持分数坐标与笛卡尔坐标。
文件 I/O：CIF、POSCAR、XYZ、JSON 等格式的解析与写出，并识别表示损失。
对称性分析：SpacegroupAnalyzer 支持 symprec（Å）与 angle_tolerance（度）参数，可生成容差敏感性报告。
结构变换：通过 TransformedStructure 记录变换历史，支持超胞、取代等标准变换。
本地相图：基于严格 JSON schema 的离线相图生成，要求总能量与修正方案一致。
电子结构：解析 VASP 的 vasprun.xml（能带、DOS），以及 Q-Chem 的输入输出。
Materials Project：通过 mp-api 的 MPRester 访问，默认仅做干跑规划，需显式 --execute 才执行有界查询。
捆绑 CLI：composition_structure_validator.py、structure_analyzer.py、symmetry_sensitivity_report.py、io_conversion_plan.py、structure_converter.py、phase_diagram_generator.py、mp_query.py、artifact_manifest.py。

使用方式

安装（需 Python 3.11+）：

uv init --python 3.11
uv add "pymatgen==2026.5.4" "pymatgen-core==2026.7.16" "mp-api==0.46.4"
uv lock
uv sync --frozen

一次性环境：

uv venv --python 3.11 .venv-pymatgen
uv pip install --python .venv-pymatgen/bin/python \
  "pymatgen==2026.5.4" "pymatgen-core==2026.7.16" "mp-api==0.46.4"

核心对象示例：

from pymatgen.core import Composition, Element, Lattice, Molecule, Structure

composition = Composition("LiFePO4", strict=True)
iron = Element("Fe")

lattice = Lattice.cubic(5.64)  # Å
structure = Structure(
    lattice,
    ["Na", "Cl"],
    [[0, 0, 0], [0.5, 0.5, 0.5]],
    coords_are_cartesian=False,
    validate_proximity=True,
)

结构校验：

python scripts/composition_structure_validator.py composition "Fe2O3"
python scripts/composition_structure_validator.py structure structure.cif
python scripts/structure_analyzer.py structure.cif --symmetry

对称性敏感性报告：

python scripts/symmetry_sensitivity_report.py structure.cif \
  --symprec 0.001,0.01,0.1 --angle-tolerance 1,5

转换规划与执行：

python scripts/io_conversion_plan.py \
  --input input.cif --input-format cif \
  --output POSCAR.new --output-format poscar \
  --periodic --coordinate-mode direct

python scripts/structure_converter.py input.cif POSCAR.new \
  --output-format poscar --coordinate-mode direct --allow-lossy \
  --acknowledge-parser-warnings

Materials Project 查询（默认干跑）：

python scripts/mp_query.py \
  --chemsys Li-Fe-O \
  --energy-above-hull 0 0.05 \
  --fields formula_pretty,energy_above_hull,band_gap,origins \
  --limit 25

适用场景

晶体与分子结构的解析、校验、格式转换与变换。
对称性指派与容差敏感性分析。
基于本地计算条目的相图构建。
VASP 能带与 DOS、Q-Chem 输入输出的解析。
通过 mp-api 有界查询 Materials Project 数据。

限制

所有解析、转换、对称性指派与数据库结果均依赖方法与参数，需记录单位、坐标模式、警告与版本。
CIF、POSCAR、XYZ、JSON 语义不同，转换可能丢失信息，需写入新路径并做往返检查。
相图仅基于提供的条目集，计算在凸包上不代表实验稳定性。
数据库访问默认关闭，需显式执行并披露端点、过滤、字段、结果上限、缓存、输出、许可与引用。
不得使用 pickle 或加载不可信对象图，应使用 schema 校验的 JSON 与显式构造器。
解析器处理攻击者可控输入，需隔离并限制 CPU/RAM/磁盘/时间；2024.2.8 及更早版本存在恶意 CIF 代码执行漏洞，2024.2.20 修复。
POTCAR 受 VASP 许可，pymatgen 不分发，不得再分发或扫描无关目录。
pymatgen 不授予 VASP 或 Q-Chem 许可，也不确立方法有效性。
版本采用日期式编号，PyPI 以点号呈现，不能据此推断语义化版本兼容性。
具体收费、价格与平台信息暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制