pymatgen

pymatgen

使用 pymatgen 对组分、分子、周期性结构、计算条目、对称性、相图、电子结构和电子结构代码文件进行显式且保留溯源信息的处理。请注意，每次解析、转换、对称性指派、变换和数据库查询结果都取决于所用方法和参数。

MIT 前置元数据中的许可证适用于此技能。pymatgen 和 pymatgen-core 采用 MIT 许可证；mp-api 声明采用 BSD-3-Clause-LBNL 许可证。Materials Project 数据通常采用 CC BY 4.0 许可证，而贡献数据仍归其贡献者所有。重新分发前，请核查具体制品和数据的许可条款。

已验证快照（2026-07-23）

• pymatgen==2026.5.4 是最新稳定版包装程序发行版（2026-05-04）。 软件包元数据要求 Python 3.11+，并直接依赖 pymatgen-core>=2026.4.16。
• pymatgen-core==2026.7.16 是最新稳定版核心发行版（2026-07-16）。 现在，核心对象、对称性／晶格运算和 I/O 层均包含在其中， 并沿用现有的 pymatgen.* 命名空间。
• mp-api==0.46.4 是最新稳定版 Materials Project 客户端 （2026-06-15），要求 Python 3.11+，并依赖 pymatgen>2024.2.20。
• 当前 API 网站基于 2026.7.16 核心文档构建。固定这两个 发行版的版本，可避免 pymatgen==2026.5.4 悄然解析到 不同的未来核心版本。
• Pymatgen 使用基于日期的版本号。PyPI 会用点号显示日期；请勿 根据数字推断语义化版本兼容性。

创建项目锁定文件以确保可复现：

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"

直接固定版本并不会锁定所有传递依赖的 wheel。请保留 uv.lock、平台、 Python 版本、软件包版本和制品哈希值。

必需工作流

1. 说明对象是非周期性的 Molecule 还是周期性的 Structure；记录晶格和周期性边界条件。
2. 说明单位。Pymatgen 常用 Å、度、eV、eV/原子、amu 和 g/cm³，但应以各 API 文档中的约定为准。
3. 说明坐标模式。Structure 坐标默认为分数坐标，除非设置 coords_are_cartesian=True；Molecule 坐标为笛卡尔坐标。
4. 检查每条解析器警告。对于 CIF，请保留占位率、位点合并、化学计量和 修正相关警告；不要默默接受修复。
5. 报告无序／部分占位情况和氧化态标注。绝不要隐式猜测氧化态。
6. 在进行对称性、邻居、变换、转换或热力学分析之前，先运行验证。
7. 扫描对称性容差，并在每次指派时报告以 Å 为单位的 symprec 和 以度为单位的 angle_tolerance。
8. 将变换视为新制品。保留输入、参数、软件版本、警告以及父项／子项校验和。
9. 转换前，明确表示形式会丢失哪些信息。仅写入新路径，并对科学相关属性进行 往返检查。
10. 仅使用总能量和修正方案兼容的条目构建相图。计算得到的凸包取决于所提供的条目集。
11. 默认关闭所有数据库访问。执行前，应明确说明端点、筛选条件、字段、结果上限、 缓存行为、输出、许可证和引用信息。
12. 保留制品清单。绝不使用 pickle 或加载不受信任的通用对象图；请使用经过架构验证的 JSON 和显式构造函数。

核心对象

使用公开的便捷导入：

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,
)

molecule = Molecule(
    ["O", "H", "H"],
    [[0.0, 0.0, 0.0], [0.758, 0.0, 0.504], [-0.758, 0.0, 0.504]],
    charge=0,
    spin_multiplicity=1,
)

Structure 和 Molecule 是可变对象；若修改会损害溯源信息，请使用 IStructure／IMolecule 或显式副本。参见 核心类。

安全的本地结构导入

优先使用捆绑的验证器，它会捕获 CIF 和 Python 警告，并报告单位、占位率、无序、氧化态、周期性、坐标模式和最小距离：

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

直接处理 CIF 时，请使用当前的解析器方法，并检查两类警告：

import warnings
from pymatgen.io.cif import CifParser

with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    parser = CifParser("input.cif", check_cif=True)
    structures = parser.parse_structures(
        primitive=False,
        check_occu=True,
        on_error="raise",
    )

parser_messages = list(parser.warnings)
python_messages = [str(item.message) for item in caught]

不要在特权进程中解析不可信文件。一个严重的恶意 CIF 代码执行漏洞影响了截至 2024.2.8 的 pymatgen，并已在 2024.2.20 中修复；固定的版本更新，但解析器仍会处理攻击者控制的输入。请使用隔离环境，并限制 CPU、RAM、磁盘和时间。

对称性

空间群的判定取决于容差和结构质量：

from pymatgen.symmetry.analyzer import SpacegroupAnalyzer

analyzer = SpacegroupAnalyzer(
    structure,
    symprec=0.01,          # Å
    angle_tolerance=5.0,   # degrees
)
symbol = analyzer.get_space_group_symbol()
number = analyzer.get_space_group_number()

Materials Project 流程通常使用 symprec=0.1 Å，而 pymatgen 文档中给出的默认值为 0.01 Å；这可能导致不同的判定结果。请生成敏感性报告，而不要不断更改容差，直到得到偏好的结果：

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

请参阅分析模块。

转换与解析器/写入器 I/O

请先制定计划；规划器不会打开文件，也不会导入 pymatgen：

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

CIF、POSCAR、XYZ 和 JSON 无法保留相同的语义。每次转换后，请检查晶格、周期性、坐标模式、物种顺序、选择性动力学、位点属性、氧化态、标签和无序。请参阅I/O 格式。

转换与来源记录

转换副本并保留历史记录：

from pymatgen.alchemy.materials import TransformedStructure
from pymatgen.transformations.standard_transformations import (
    SubstitutionTransformation,
    SupercellTransformation,
)

tracked = TransformedStructure(structure.copy(), [])
tracked.append_transformation(SupercellTransformation([2, 2, 2]))
tracked.append_transformation(SubstitutionTransformation({"Na": "K"}))
derived = tracked.final_structure
history = tracked.history

一对多的有序化、掺杂、薄板和磁性转换可能产生组合爆炸，或调用可选的可执行文件。请限制候选项、位点、超胞大小、运行时间和输出数量。请参阅转换与工作流。

局部相图

捆绑的生成器可离线运行，并且只接受严格的 JSON 架构，其中包含每个条目的总 eV 能量和来源信息：

{
  "schema_version": "1.0",
  "energy_unit": "eV",
  "energy_basis": "total_per_entry",
  "provenance": {
    "source": "reviewed local calculations",
    "method": "one compatible energy/correction scheme"
  },
  "entries": [
    {
      "entry_id": "local-Li",
      "composition": "Li",
      "energy_eV": -1.0,
      "provenance": {"source": "calculation manifest sha256:..."}
    }
  ]
}

python scripts/phase_diagram_generator.py entries.json --analyze Li2O

必须包含元素端点和所有竞争相。不要混合来自不同泛函、赝势、磁性状态或修正规则的原始能量。计算得到的凸包上状态不等于实验稳定性。

能带结构、DOS、VASP 和 Q-Chem

只解析所需的数据：

from pymatgen.io.vasp import Vasprun

run = Vasprun(
    "vasprun.xml",
    parse_dos=True,
    parse_eigen=True,
    parse_projected_eigen=False,
    parse_potcar_file=False,
)
band_structure = run.get_band_structure(line_mode=True)
band_gap = band_structure.get_band_gap()
complete_dos = run.complete_dos

投影本征值可能需要极大的内存。解释带隙或 DOS 前，请核实收敛性、k 路径、自旋/SOC 设置、费米能级约定、展宽和投影基组。解析成功并不代表计算已收敛。

当前的 Q-Chem 接口为 pymatgen.io.qchem.inputs.QCInput 和 pymatgen.io.qchem.outputs.QCOutput：

from pymatgen.io.qchem.inputs import QCInput

job = QCInput(
    molecule,
    rem={"job_type": "sp", "method": "wb97x-v", "basis": "def2-svpd"},
)
text = str(job)

Pymatgen 可以编写输入文件并解析输出文件；它不会授予 VASP 或 Q-Chem 许可证，也无法证明方法有效。POTCAR 文件受 VASP 许可约束，且 pymatgen 不会分发这些文件。绝不要重新分发这些文件，也不要扫描无关目录来查找它们。enumlib、Bader、packmol、ffmpeg 和 Zeo++ 等可选工具属于原生/外部可执行文件：在单独明确调用前，请审查其来源、许可证、argv、工作目录和资源限制。

Materials Project：联网前先规划

仅使用：

from mp_api.client import MPRester

客户端在构造时读取 MP_API_KEY。只能通过用户的 shell 或密钥管理器提供这个指定的环境变量。不要将密钥作为 CLI 参数接收，不要遍历 .env 文件，不要转储环境变量，也不要在未脱敏的情况下打印异常数据。

默认采用试运行规划：

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

只有 --execute 才允许执行一次有界摘要查询，并且要求使用新的输出路径：

python scripts/mp_query.py \
  --material-id mp-149 \
  --fields formula_pretty,structure,origins,last_updated \
  --limit 1 --output mp-149.json --execute

CLI 会设置 num_chunks=1，要求显式指定字段和筛选条件，限制结果数量，不实现隐式结果缓存，也绝不会覆盖输出。初始化 MPRester 还会请求兼容性／心跳元数据；规划会披露这些请求、禁用包含平台详细信息的 user agent 和本地数据库版本通知日志，并记录返回的数据库版本。摘要工作流不会请求完整数据集缓存下载。 mp-api 0.46.4 会根据自身配置的策略重试 HTTP 429/502/504，并遵循 Retry-After；不要臆造数值化的服务配额，也不要添加无界重试循环。

Materials Project 的核心数值是依赖计算方法的计算数据，而非实验真值。PBE 通常会高估晶格参数，并系统性低估带隙；聚合值可能随数据库版本更新而变化。请保留检索时间、查询、字段、材料／任务来源、可用时的数据库版本、客户端版本、CC BY 署名信息，以及通用引用和属性专属引用。请参阅 Materials Project API。

内置 CLI

所有 CLI 均提供无依赖的 --help、延迟加载科学计算库、有界 JSON 输出，且不会隐式联网：

• scripts/composition_structure_validator.py — 严格检查成分／结构；可选的氧化态猜测需显式启用且有界。
• scripts/structure_analyzer.py — 生成有界的晶格、位点、对称性、距离及可选 CrystalNN 报告。
• scripts/symmetry_sensitivity_report.py — 容差网格空间群报告。
• scripts/io_conversion_plan.py — 无依赖的表示损失规划。
• scripts/structure_converter.py — 将单个文件转换到新路径。
• scripts/phase_diagram_generator.py — 严格的本地计算条目凸包。
• scripts/mp_query.py — MP 查询试运行规划及可选启用的有界客户端。
• scripts/artifact_manifest.py — 校验和、版本、来源及溯源信息。

使用：

python scripts/artifact_manifest.py \
  --artifact input.cif --artifact analysis.json \
  --workflow "local symmetry sensitivity" --output manifest.json

参考资料

• 核心类
• I/O 格式、VASP 和 Q-Chem
• 分析、对称性、相图、能带和 DOS
• 变换和工作流
• Materials Project API、溯源、许可和限制

来源（已于 2026-07-23 核实）

• PyPI 上的 pymatgen 2026.5.4
• PyPI 上的 pymatgen-core 2026.7.16
• pymatgen API 文档
• pymatgen 更新日志
• PyPI 上的 mp-api 0.46.4
• Materials Project API 入门指南
• Materials Project 查询指南
• Materials Project 常见问题及计算数据注意事项
• Materials Project 引用页面
• 由 pymatgen 背书的官方教程系列

Agent 操作流程

1. 检查环境。 确认库版本、单位、坐标系和数据格式（FITS、CIF、HDF5、netCDF）。
2. 明确输入。 根据数据或用户提供的信息确认格式、标识符和参数。任何会改变结果的值都应询问，不要猜测。
3. 先运行小规模版本。 在较小的网格、区域或子集上运行，并检查物理合理性。
4. 使用上述说明和参考资料 执行完整任务。
5. 验证结果。 检查单位和量纲一致性、守恒定律或已知极限，以及数值收敛性。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果发生以下情况	请执行以下操作
结果违反已知的物理极限	报告前检查单位、边界条件和求解器容差。
这些说明中提到的函数、标志或端点在已安装的版本中缺失	查看已安装版本自己的文档（help()、--help、官方文档），调整方案并告知用户。切勿编造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所采用的假设。

诚信规则

• 切勿捏造结果、参数、标识符、引用或统计数据。如果无法运行或验证某项内容，请如实说明。
• 对每项定量结果，都要报告不确定性和数值容差。
• 请将此处与特定版本有关的细节视为可能已过时：对照已安装版本的官方文档进行确认。
• 对于需要付费、会占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，请先征求同意。

相关技能

• molfeat：使用 molfeat（0.11.0）将 SMILES 字符串或 RDKit/datamol 分子转换为数值特征。molfeat 提供计算器、scikit-learn…
• protocolsio-integration：使用文档所述的 REST v3/v4 端点和官方 MCP 端点读取、验证并导出 protocols.io 数据，并构建非 exe…