pymatgen 材料科学 Agent 技能实战指南：可溯源的结构校验、相图与 Materials Project 查询工作流-平芜编程栈

pymatgen 材料科学 Agent 技能实战指南：可溯源的结构校验、相图与 Materials Project 查询工作流

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills

本指南基于 scientific-agent-skills 仓库中的pymatgenAgent Skill（SKILL.md），系统讲解如何在 AI Agent 工作流中使用 pymatgen 完成组分（Composition）、分子（Molecule）、周期结构（Structure）、计算条目（ComputedEntry）、对称性、相图、电子结构及 VASP/Q-Chem 文件的解析与转换，并给出显式边界约束下的 Materials Project 查询方案。读完本文，你将掌握一套"先规划、后执行、全链路溯源"的材料科学数据处理方法论，能够复现本 Skill 提供的全部 CLI 工具与核心 API 用法。

背景：为什么材料科学数据操作必须"方法可溯源"

pymatgen（Python Materials Genomics）是材料科学领域最常用的计算材料学工具库，覆盖从化学式解析、晶体结构建模、对称性分析、相图计算到 VASP/Q-Chem 输入输出、Materials Project 数据库查询的完整链路。但本 Skill 反复强调一个核心理念：每一次解析、转换、对称性指派、变换和数据库查询结果都依赖具体方法与参数——解析器有容差，对称性指派依赖symprec，相图依赖能量集合，数据库值依赖计算方法与版本。因此，AI Agent 在自动处理材料数据时，必须把"方法依赖"显式记录下来，形成可复现的溯源链，而不是把任何中间结果当作客观事实。

本 Skill 的许可证边界如下：Skill 本体采用 MIT 许可；pymatgen与pymatgen-core为 MIT；mp-api声明 BSD-3-Clause-LBNL；Materials Project 数据一般遵循 CC BY 4.0，贡献者自有数据归贡献者所有。在进行任何再分发前，请核查具体工件与数据的许可条款。

验证快照与依赖锁定（Verified Snapshot）

Skill 在 2026-07-23 核验了一组精确版本组合，Agent 应严格锁定它们，避免依赖漂移：

发行版	版本	说明
`pymatgen`	2026.5.4（2026-05-04 发布）	最新稳定 wrapper，元数据要求 Python 3.11+，直接依赖`pymatgen-core>=2026.4.16`
`pymatgen-core`	2026.7.16（2026-07-16 发布）	最新稳定 core，核心对象、对称性/晶格操作与 I/O 层已迁入此包，但仍保留原有`pymatgen.*`命名空间
`mp-api`	0.46.4（2026-06-15 发布）	最新稳定 Materials Project 客户端，要求 Python 3.11+，依赖`pymatgen>2024.2.20`

为什么同时固定两个发行版？因为pymatgen==2026.5.4对 core 的依赖是>=2026.4.16，如果不固定pymatgen-core，未来某个新 core 版本可能被静默解析进来。还需注意：pymatgen 使用日期型版本号，PyPI 渲染时用点号分隔（如 2026.5.4），不能把其中的数字推断为语义化版本兼容性。

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

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"

直接 pin 不会冻结所有传递依赖的 wheel。必须保存uv.lock、平台信息、Python 版本、包版本与工件哈希。Skill 自带的 CLI 在 scripts/_common.py 中同样固化了这组版本常量（PYMATGEN_VERSION、PYMATGEN_CORE_VERSION、MP_API_VERSION），并在网络执行前强制校验安装版本与预期快照一致，例如 scripts/mp_query.py 中expected与installed不匹配即报错。

必需工作流：12 条前置规则

本 Skill 在进入任何具体操作前，强制 Agent 遵守以下 12 条规则，它们构成了材料数据处理的"安全基线"：

先声明对象类型是非周期Molecule还是周期Structure，记录晶格与周期性边界条件。
声明单位。pymatgen 常用 Å、度、eV、eV/atom、amu 与 g/cm³，但每个 API 的文档约定优先。
声明坐标模式。Structure坐标默认为分数坐标（除非coords_are_cartesian=True）；Molecule坐标为笛卡尔坐标。
检查每一个解析器警告。对于 CIF，保留 occupancy、位点合并、化学计量与修正相关警告，不要静默接受"修复"。
报告无序/部分占据与氧化态装饰。绝不隐式猜测氧化态。
在对称性、邻居、变换、转换或热力学分析之前先运行校验。
扫描对称性容差，并在每次指派时报告以 Å 为单位的symprec和以度为单位的angle_tolerance。
将变换视为新工件。保留输入、参数、软件版本、警告与父/子校验和。
转换前识别表征丢失（representation loss）。只写入新路径，并对科学相关属性做往返（round-trip）检查。
只用兼容的总能与修正方案构建相图。计算 hull 依赖于所提供的条目集合。
所有数据库访问默认关闭。在显式执行步骤前披露端点、过滤条件、字段、结果上限、缓存行为、输出、许可与引用。
保留工件清单。绝不使用 pickle 或加载不可信的一般对象图；使用 schema 校验过的 JSON 与显式构造器。

核心对象：Composition、Element、Lattice、Structure、Molecule

优先使用公共便捷导入：

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或显式copy()。更完整的类说明见 references/core_classes.md。

Element、Species 与 Composition 的语义边界

从 references/core_classes.md 可以提炼出几条关键区分：

Element.symbol是化学符号，Element.Z是原子序数，Element.X是 Pauling 电负性——不要混淆。
Species附加氧化态；氧化态是正式的化学标注，不是经自动校验的电荷模型。
DummySpecies是建模标签，不是物理原子。
严格解析外部边界时使用Composition("LiFePO4", strict=True)，也可以用映射构造Composition({"Fe": 2, "O": 3}, strict=True)。
完整式（formula）与约化式（reduced_formula）必须区分保存，约化会丢失整数比例。
oxi_state_guesses()是启发式方法且可能呈组合爆炸，只能在用户显式批准后调用，并限制元素数、配方大小、运行时间与返回的猜测数量。

Lattice 与坐标安全

晶格矩阵的行是晶格矢量。构造方式包括Lattice.cubic(5.64)、Lattice.from_parameters(a, b, c, alpha, beta, gamma)与直接传入矩阵的Lattice([...], pbc=(True, True, True))。必须保留：矩阵与 (a,b,c)、(alpha,beta,gamma)、行列式/体积与手性、PBC 元组，以及该晶胞是否经过约化、标准化、应变或变换。Niggli/LLL 约化与晶体学标准化会改变晶胞基矢和位点坐标，产生的是新的表示，同样需要溯源。

分数坐标落在[0, 1)之外可能是合法的周期镜像，包裹（wrap）是一种变换而非自动修复。校验器在 scripts/composition_structure_validator.py 中逐位点检查占据和、坐标有限性与是否越出规范晶胞，并在最小距离检查超过二次复杂度上限时显式告警（该文件设置了--max-distance-sites默认 500，绝对上限ABSOLUTE_MAX_PAIRWISE_SITES = 1_000）。

氧化态装饰

decorated = structure.copy() decorated.add_oxidation_state_by_element({"Na": 1, "Cl": -1})

这会在副本上产生变更，需保留未装饰的父结构、映射、方法与电荷平衡假设。add_oxidation_state_by_guess()是启发式的，不得隐式调用。

显式 JSON 序列化

import json from pymatgen.core import Structure payload = structure.as_dict() text = json.dumps(payload, allow_nan=False, sort_keys=True) decoded = json.loads(text) restored = Structure.from_dict(decoded)

对于不可信 JSON：强制字节/嵌套/集合/字符串上限，拒绝重复键与非有限数，校验期望的Structureschema，并调用具体类构造器。不要使用 pickle，也不要将攻击者可控的 MSON 元数据交给会动态导入类的通用解码器——JSON 只是语法，schema 校验才是信任边界。

安全的本地结构摄入（Safe Local Structure Intake）

Skill 优先推荐其捆绑校验器，它会同时捕获 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

校验器不修改任何文件，默认不猜测氧化态；只有显式--guess-oxidation-states才运行有界的氧化态猜测器（限制 6 个元素、100 个原子、最多返回 20 个猜测，见 scripts/composition_structure_validator.py）。

直接使用 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]

从 references/io_formats.md 可以确认更完整的 CIF 解析参数语义：occupancy_tolerance控制略超 1 的占据是否被重标定，site_tolerance控制邻近位点是否合并，frac_tolerance可能把坐标取整到常见分数，check_cif会比较解析结构组分与 CIF 组分并提示遗漏（如难以定位的氢）。parse_structures(primitive=False)是当前显式行为，不要依赖历史默认值。

安全警示：一个严重的恶意 CIF 代码执行漏洞影响了 2024.2.8 及更早的 pymatgen，并在 2024.2.20 修复。本 Skill pin 的版本已更新，但解析器仍处理攻击者可控输入，必须使用低权限隔离进程并施加 CPU/内存/磁盘/时间限制。

对称性分析：容差决定一切

空间群指派依赖于容差与结构质量：

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

从 references/analysis_modules.md 可以看到，完整结果还应记录get_crystal_system()、get_point_group_symbol()、get_symmetry_operations()数量、get_symmetrized_structure()的等效位点索引与 Wyckoff 符号。指派结果还会随坐标精度、占据/无序模型、是否使用氧化态/自旋/位点属性、原胞/惯例胞表示以及 spglib 版本变化。标准化或原胞结构是新的表示：

conventional = analyzer.get_conventional_standard_structure( keep_site_properties=False ) primitive = analyzer.get_primitive_standard_structure( keep_site_properties=False )

位点属性可能丢失或未做对称性感知的传播，需保留父结构并比较组分、每原子体积、磁序与属性语义。

I/O 转换：先规划、后执行、识别表征丢失

I/O 解析与写出不是中性的字节操作。转换前必须记录对象类型、输入/输出格式与变体、晶格/PBC 与坐标模式、单位、物种顺序/标签/占据/无序/氧化态、分子的电荷/自旋、位点属性（选择性动力学、速度、力、磁矩）以及解析器警告与自动修正。

便捷接口

from pymatgen.core import Molecule, Structure structure = Structure.from_file("input.cif", primitive=False, sort=False) cif_text = structure.to(fmt="cif") poscar_text = structure.to(fmt="poscar") molecule = Molecule.from_file("molecule.xyz") xyz_text = molecule.to(fmt="xyz")

文件名或扩展名有歧义时使用显式fmt。永远不要覆盖输入或已有输出；写入新工件、往返解析、比较工作流所依赖的属性。

表征丢失的现实

CIF：一个 CIF 可含多个 data block/结构，需显式选择索引；写入时CifWriter的symprec会触发找对称并可能细化为惯例表示，必须报告symprec、angle_tolerance与refine_struct（见 references/io_formats.md）。
POSCAR/CONTCAR：无法忠实表示部分占据；氧化态与任意位点属性通常不能往返。记录 direct/Cartesian、缩放因子、VASP 4 文件元素名来源、物种顺序、选择性动力学标志与速度。不要为"修复" POSCAR 而在邻近目录搜索 POTCAR。
XYZ 及其他低上下文格式：XYZ 是笛卡尔、非周期格式，转出会丢失晶格与周期性；也不定义氧化态、部分占据、键、电荷、自旋多重度与位点属性。CSSR 与 XSF 各有其表征极限——Structure.to()支持某格式是句法能力，不是无损证明。

本 Skill 的两步转换流程

第一步，用无依赖规划器生成表征丢失计划（不打开文件、不导入 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 并不保留相同的语义。每次转换后都要检查晶格、周期性、坐标模式、物种顺序、选择性动力学、位点属性、氧化态、标签与无序。完整的安全转换序列见 references/io_formats.md：清点源字节与校验和 → 校验表示不变量 → 生成干跑丢失计划 → 拒绝不兼容目标（如无序结构转 POSCAR）→ 显式确认残余丢失 → 内存渲染并施加输出字节上限、独占新建 → 在相同安全边界下重新解析 → 显式数值容差比较 → 双校验和与警告入清单。

变换与溯源：变换是科学假设，不是清理

变换会创造科学假设与派生结构，绝非无害的"清理"。务必保留原始结构、显式假设、约束候选增长、记录父/子校验和。变换的基本契约是apply_transformation(structure, ...)：一对一变换返回结构，一对多变换在显式请求时可返回排序字典。

用 TransformedStructure 跟踪历史

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

history 有用但不足以构成完整溯源，还需额外保存输入/输出校验和、警告流、精确版本与依赖锁、用户意图与验收标准、单位与坐标约定、外部可执行文件元数据。

常用变换要点

超胞：SupercellTransformation([2, 2, 2])（或矩阵形式[[2,0,0],[0,2,0],[0,0,2]]）。检查缩放矩阵行列式为正整数、位点计数倍增、每点位体积一致、PBC 与内存增长；非对角矩阵会改变晶胞基矢与位点排序。
取代：完整取代{"Fe": "Mn"}；部分取代{"Fe": {"Fe": 0.5, "Mn": 0.5}}会创建无序——那是平均/无序表示，不是某个有序原子构型。
移除物种：RemoveSpeciesTransformation(["H"])会改变组分、电荷与连接性，绝不能当作静默解析清理。
原胞/惯例胞：PrimitiveCellTransformation(tolerance=0.5)与ConventionalCellTransformation(symprec=0.01, angle_tolerance=5)依赖对称性容差，可能改变位点顺序或属性。
无序有序化：OrderDisorderedStructureTransformation可能组合爆炸，必须用return_ranked_list=20之类显式上限，并预先验证理性占据与所需超胞、按需提供氧化态、设定候选/运行时间/RAM/磁盘上限。排名第一的有序构型是模型依赖结果，不是唯一基态。
枚举与 enumlib：EnumerateStructureTransformation及磁序等高级变换依赖外部原生程序enum.x/makestr.x。必须核验官方来源、版本、构建说明、许可与哈希，显式解析可执行路径，审查 argv 与工作目录，隔离不可信输入并施加各类上限——不要自动安装或调用。

更完整的变换清单与"无序到有界有序候选"等参考工作流见 references/transformations_workflows.md。

本地相图：严格 schema 与可比性闸门

本 Skill 的相图生成器离线运行，只接受严格 JSON schema，能量为每个条目的总 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

从源码 scripts/phase_diagram_generator.py 可以看到 schema 校验是硬性的：顶层键必须恰好为schema_version/energy_unit/energy_basis/provenance/entries，schema_version必须等于"1.0"，energy_unit必须为"eV"，energy_basis必须为"total_per_entry"；每个条目的键必须恰好为entry_id/composition/energy_eV/provenance，entry_id不得重复，组分用Composition(formula, strict=True)严格解析。该脚本还支持--plot输出 .png/.pdf/.svg 相图（限最多 4 个元素），通过同目录临时文件加原子链接（os.link）写入，绝不覆盖已有文件。

可比性闸门（Comparability Gate）

构建 hull 前必须确认条目共享兼容的：泛函与修正/混合方案、赝势族与价电子构型、磁/自旋/SOC 处理、参考态约定、数值收敛水平、温度/压力模型。必须包含元素端点与所有相关竞争相——缺少竞争相会让不稳定条目"看起来稳定"。重复组分仅在能量可比且溯源可区分时才能作为多形体存在。

from pymatgen.analysis.phase_diagram import PhaseDiagram from pymatgen.entries.computed_entries import ComputedEntry entries = [ ComputedEntry("Li", -1.0, entry_id="local-Li"), ComputedEntry("O2", -2.0, entry_id="local-O2"), ComputedEntry("Li2O", -4.0, entry_id="local-Li2O"), ] diagram = PhaseDiagram(entries) for entry in entries: print( entry.entry_id, diagram.get_form_energy_per_atom(entry), diagram.get_e_above_hull(entry), )

ComputedEntry.energy是所表示组分的总 eV，不是eV/atom；energy_per_atom、生成能与 hull 距离才是归一化值。diagram.stable_entries表示该精确条目集合下计算出的零温凸包上的相，不是实验稳定性或可合成性。

电子结构 I/O：VASP 与 Q-Chem

Vasprun 解析：只解析所需数据

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

投影本征值可能消耗极端内存，务必保持parse_projected_eigen=False（除非确实需要且有资源边界）。解析成功后仍要核实收敛性、k 路径、自旋/SOC 设置、Fermi 能级约定、smearing 与投影基。解析成功不等于计算收敛。

从 references/io_formats.md 还可以看到：只用能带信息时可用BSVasprun优化解析；get_band_structure()返回BandStructure或BandStructureSymmLine，方法包括is_metal()、get_band_gap()、get_vbm()、get_cbm()；complete_dos支持 total、元素、位点与轨道投影 DOS。大型 XML/HDF5/CHGCAR/LOCPOT/WAVECAR 文件需要显式字节与内存上限。

VASP 输入集与 POTCAR 边界

from pymatgen.io.vasp import Incar, Kpoints, Poscar from pymatgen.io.vasp.sets import MPNonSCFSet, MPRelaxSet, MPStaticSet incar = Incar({"ENCUT": 520, "ISMEAR": 0, "SIGMA": 0.05}) kpoints = Kpoints.automatic_density(structure, 1000) poscar = Poscar(structure) relax = MPRelaxSet(structure) static = MPStaticSet(structure) bands = MPNonSCFSet(structure, mode="line")

输入集编码了版本化方法学选择。写盘前必须检查生成的 INCAR/KPOINTS/POSCAR/POTCAR 规范，记录输入集类、pymatgen/core 版本、所有用户覆盖与源结构校验和，写入新的计算目录。POTCAR 数据集是 VASP 许可的，pymatgen 不随库分发；POTCAR.spec不是 POTCAR，不得再分发赝势内容或静默使用无关安装的文件。

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)

QCInput接受rem、opt、pcm、solvent、smx、scan、plots、nbo、geom_opt等显式分段。每个设置都应对照持牌的 Q-Chem 版本与手册校验；保留分子原子顺序、电荷、自旋多重度、方法/基组、溶剂模型、任务类型与输入文本。QCOutput解析为结构化数据后，使用结果前需检查解析错误、完成度、SCF/几何收敛、虚频与单位。

pymatgen 只负责写输入、读输出，不授予 VASP 或 Q-Chem 许可，也不建立方法有效性。enumlib、Bader、packmol、ffmpeg、Zeo++ 等可选外部工具是原生程序，需在单独显式调用前核验来源、许可、argv、工作目录与资源限制。

Materials Project：先规划，再联网

认证：唯一命名的机密

只使用：

from mp_api.client import MPRester

客户端在构造时读取MP_API_KEY。只通过用户的 shell 或机密管理器注入这一个命名环境变量；不要把密钥作为 CLI 参数、遍历.env文件、转储环境变量，或打印未脱敏的异常数据。从 references/materials_project_api.md 可知，正确的模式是with MPRester() as rester:——读取已注入的MP_API_KEY。本 Skill 的 CLI 只会在--execute之后读取该变量（见 scripts/mp_query.py），并在所有异常路径用safe_error_message(..., secret=api_key)脱敏（scripts/_common.py）。

干跑规划是默认

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 的硬性约束（scripts/mp_query.py）：结果上限MAX_RESULTS=100、字段上限MAX_FIELDS=20、材料 ID 上限 100 个且必须匹配^(?:mp|mvc)-[0-9]+$；字段名必须匹配^[A-Za-z][A-Za-z0-9_]{0,79}$。query_contract()把显式过滤器组装成search_kwargs，固定num_chunks=1、chunk_size=limit、all_fields=False，并强制要求至少一个查询过滤器。CLI 无隐式结果缓存、永不覆盖输出；执行前还会用rester.materials.summary.available_fields校验请求字段在端点真实可用。

MPRester初始化本身会执行兼容性/heartbeat 元数据请求；CLI 会披露这些请求、关闭平台详情 user-agent 与本地数据库版本通知日志，并记录服务器返回的数据库版本。摘要工作流不请求全数据集缓存下载。mp-api0.46.4 按自身配置策略对 HTTP 429/502/504 重试并尊重Retry-After——不要编造数字服务配额，也不要添加无界重试循环。

Summary 搜索与过滤器

with MPRester() as rester: docs = rester.materials.summary.search( chemsys="Li-Fe-O", elements=["Li", "O"], exclude_elements=["F"], energy_above_hull=(0.0, 0.05), band_gap=(0.5, 3.0), is_stable=None, fields=["material_id", "formula_pretty", "energy_above_hull", "band_gap"], all_fields=False, num_chunks=1, chunk_size=25, )

要点：material_ids接受单个 ID 或列表；exclude_elements是元素符号列表而不是布尔标志；available_fields只说明端点可返回的字段，不代表每个字段都是合法过滤器；默认all_fields=True很昂贵，务必传短fields列表并限制分块。结果默认是SummaryDoc模型对象列表，通过document.model_dump(mode="json")序列化为严格 JSON（CLI 在 scripts/mp_query.py 中实现了这一接口）。

条目、结构与能带便捷方法

with MPRester() as rester: entries = rester.get_entries_in_chemsys( "Li-Fe-O", compatible_only=True, conventional_unit_cell=False, ) structure = rester.get_structure_by_material_id( "mp-149", final=True, conventional_unit_cell=False, ) bands = rester.get_bandstructure_by_material_id("mp-149") dos = rester.get_dos_by_material_id("mp-149")

get_entries_in_chemsys还接受use_gibbs、property_data与additional_criteria（如{"thermo_types": ["GGA_GGA+U", "GGA_GGA+U_R2SCAN", "R2SCAN"]}）。不要随意混合热力学类型或修正方案。能带/DOS 便捷方法可能返回None（数据不可用）——不要把一个缺失对象当作零带隙或零 DOS。Materials Project 结构是计算松弛表示，不一定等于实验设定、晶格参数、无序、温度或组分模型，拿回本地后仍需校验。

溯源、许可与引用

请求origins字段可以把摘要属性连接到计算任务；对应的 thermo 文档run_type区分 GGA、GGA+U、r2SCAN 等类别——不要假设一个 summary 文档上的所有属性来自同一计算或同一泛函。许可上，Materials Project 数据为 CC BY 4.0，贡献数据归贡献者；需要保存权威引用、属性/工具特定引用、数据库版本引用、材料 ID 与任务/属性来源、检索日期与查询。参考 references/materials_project_api.md 中的最小溯源信封（provenance envelope）示例：包含检索时间、端点、过滤器、字段、上限、客户端版本、数据库版本与许可，绝不包含 API 密钥。

计算数据的局限

Materials Project 文档明确：核心属性为内部模拟方法计算所得；PBE 晶格参数通常系统性高估（范德华描述差时层间误差更大）；PBE 带隙系统性低估；聚合值会随计算与数据库版本更新而变化；空间群依赖symprec（MP 流水线常用 0.1 Å）。因此：计算稳定性 ≠ 实验稳定性或可合成性；预测结构 ≠ 存在证明；缺失数据 ≠ 零；材料 ID 不保证属性记录不可变。

捆绑 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`	严格本地计算条目 hull
`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

从源码看（scripts/artifact_manifest.py），清单工具会拒绝目录、符号链接与疑似密钥文件（文件名匹配env|secret|token|credential|api[-_]?key|private[-_]?key即拒收），最多 100 个工件、总字节上限 2 GiB，输出schema_version: 1.0的清单，记录每个工件的字节数、SHA-256、媒体类型与修改时间，以及软件快照与contract承诺（无网络、无目录遍历、无符号链接跟随、不输出工件内容、不读凭据、不用 pickle、不覆盖既有文件）。

从实现角度看，这些 CLI 共享一套"安全公共层" scripts/_common.py：checked_input_file()拒绝 URL 与符号链接并强制字节上限，checked_output_file()拒绝..路径与已存在输出，load_strict_json()用object_pairs_hook拒绝重复键、用parse_constant拒绝 NaN/Infinity，write_json_new()以排他方式（open("x")）创建文件。这正是本 Skill 12 条规则在代码层的落地。

深入阅读

Skill 的五个参考文档覆盖了本文各节的完整细节，建议按需深入：

核心类：显式化学、坐标与周期性
I/O 格式、VASP 与 Q-Chem
分析、对称性、相图、能带与 DOS
变换与溯源工作流
Materials Project API、溯源、许可与限制

结语

本 Skill 把 pymatgen 从"功能强大的材料学库"提升为"可溯源、有边界、方法显式的科学工作流引擎"。它的核心方法论可以浓缩为三句话：任何数值都依赖方法与参数，任何转换都产生新工件，任何数据库结果都是带溯源的计算输入而非实验真理。无论你是要用Structure/Molecule建模、用SpacegroupAnalyzer做对称性敏感分析、用phase_diagram_generator构建本地 hull，还是用mp_query.py有计划地查询 Materials Project，都应当遵循"声明单位与坐标模式 → 检查解析器警告 → 校验表示不变量 → 扫描容差与边界 → 记录完整溯源"的流程，并善用本 Skill 提供的无依赖、无隐式网络、绝不覆盖输出的八个 CLI 工具。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考