pymatgen 结构变换与溯源保留工作流实战：从 Transformation 契约到可验证派生结构的完整指南

pymatgen 结构变换与溯源保留工作流实战从 Transformation 契约到可验证派生结构的完整指南【免费下载链接】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-skillspymatgen 的 transformations 模块提供了一整套从已有结构派生新结构超胞、取代、有序化、掺杂、表面、磁性有序等的 API。但每一次变换都在生成科学假设与派生结构而不是无害的清理操作本文以 transformations_workflows.md 为核心结合本仓库 skills/pymatgen 的 SKILL 定义、配套 CLI 脚本与测试完整讲解 Transformation 契约、各类变换的正确用法与校验点、TransformedStructure 历史追踪以及六条可落地的溯源保留工作流。读完本文你将掌握如何在不破坏父结构的前提下安全派生结构、如何为每次变换记录完整的父子校验和与假设清单并用仓库自带的验证器与清单工具跑通校验—变换—产物清单的闭环。Transformation 契约每次变换都是一次假设而不是清理pymatgen 的一个变换transformation对外暴露统一的入口apply_transformation(structure, ...)。按结果数量可分为两类一对一one-to-one变换直接返回一个新的Structure一对多one-to-many变换如有序化、枚举在显式请求时return_ranked_list...返回带排名的候选字典列表。标准入口代码来自原文档见 transformations_workflows.mdfrom pymatgen.transformations.standard_transformations import ( SubstitutionTransformation, SupercellTransformation, ) parent structure.copy() supercell SupercellTransformation([2, 2, 2]).apply_transformation(parent) substituted SubstitutionTransformation({Na: K}).apply_transformation( parent )即使某个变换当前返回的是全新对象也必须保持parent不变始终先structure.copy()再对副本应用变换并用操作前的校验和checksum做断言确认父结构没有被就地修改。这与 SKILL.md 中将变换视为新产物treat transformations as new artifacts保留输入、参数、软件版本、警告和父子校验和的第 8 条要求完全一致。对每一次变换必须记录缺一不可变换类的完全限定名fully qualified class与包版本构造函数参数及依赖的默认值父产物/父校验和占据率occupancy、氧化态、电荷、自旋与 site 属性假设候选数量与排序方法产生的警告及外部可执行程序的使用情况子产物/子校验和。这套记录要求的工程化落地可以在仓库的 artifact_manifest.py 中看到它为每个显式列出的本地文件计算sha256并输出包含schema_version、workflow、sources、软件快照pymatgen/pymatgen-core/mp-api期望版本与实装版本、每个产物的bytes、media_type、modified_at_utc以及一组contract布尔字段是否访问网络、是否遍历目录、是否跟踪符号链接、是否读取凭证、是否使用 pickle、是否覆盖既有文件的清单 JSON。脚本还内置了硬性上限MAX_FILES 100、MAX_TOTAL_BYTES 2 GiB并拒绝文件名中疑似携带凭证env、secret、token、api_key等的产物。变换家族逐一拆解与校验点原文档为每一类变换都给出了最小可用示例和必须检查的物理量下面逐类展开。超胞SupercellTransformationfrom pymatgen.transformations.standard_transformations import ( SupercellTransformation, ) transformation SupercellTransformation( [[2, 0, 0], [0, 2, 0], [0, 0, 2]] ) child transformation.apply_transformation(parent)注意SupercellTransformation([2, 2, 2])与传入完整 3×3 矩阵是等价的两种写法。应用后必须检查缩放矩阵行列式是正整数期望的 site 数倍增因子与矩阵一致每 site 体积一致性volume-per-site原子/site 属性映射是否保留周期性边界条件PBC未被破坏内存与输出规模的增长是否可控。拒绝任何行列式或 site 数超过已审查上限的矩阵或候选。非对角矩阵会改变晶胞基矢与 site 排序必须显式声明这一语义变化。取代与无序SubstitutionTransformation完全取代from pymatgen.transformations.standard_transformations import ( SubstitutionTransformation, ) child SubstitutionTransformation({Fe: Mn}).apply_transformation(parent)部分取代会产生无序disorderdisordered SubstitutionTransformation( {Fe: {Fe: 0.5, Mn: 0.5}} ).apply_transformation(parent)验证要点组成、电荷模型、氧化态、占据率求和以及是否所有目标 site而非仅选中的某个子晶格都被变换。必须记住部分占据是平均/无序表示不是某一种有序原子构型——后续若将其直接当成单构型使用会引入系统性错误。移除物种RemoveSpeciesTransformationfrom pymatgen.transformations.standard_transformations import ( RemoveSpeciesTransformation, ) child RemoveSpeciesTransformation([H]).apply_transformation(parent)移除物种会改变组成、电荷并可能切断连通性connectivity。永远不要把它当作静默的解析清理手段——这正是原文档强调的Transformations are not harmless cleanup的具体体现。必须记录被移除的 site 索引/物种并在变换后校验电荷与化学计量比。原胞与惯用胞Primitive / Conventionalfrom pymatgen.transformations.standard_transformations import ( ConventionalCellTransformation, PrimitiveCellTransformation, ) primitive PrimitiveCellTransformation( tolerance0.5, ).apply_transformation(parent) conventional ConventionalCellTransformation( symprec0.01, angle_tolerance5, ).apply_transformation(parent)结果依赖对称性容差symprec单位 Å、angle_tolerance单位度且可能改变 site 顺序或 site 属性。比较时应使用化学式与每原子体积保留精确容差参数不要把不同约定的标准化胞当作字节级相同。这与 SKILL.md 中每次对称性指派都要报告symprecÅ与angle_tolerance度的第 7 条工作流要求一致仓库还提供了 symmetry_sensitivity_report.py 在容差网格上生成空间群敏感性报告而不是调到出现想要的答案为止。应变与形变DeformStructureTransformationfrom pymatgen.transformations.standard_transformations import ( DeformStructureTransformation, ) deformed DeformStructureTransformation( [[1.01, 0, 0], [0, 1.0, 0], [0, 0, 1.0]] ).apply_transformation(parent)必须声明矩阵的语义是形变梯度deformation gradient、类应变近似还是晶格变换。应用前绑定行列式、条件数、最小原子间距与应变幅度做张量拟合时应在同一 manifest 下同时生成正、负应变如1.01与0.99保证拟合数据成对可追溯。氧化态装饰氧化态是多种变换静电排序、掺杂、有序化的输入可以显式指定或猜测。优先使用有化学依据的显式映射decorated parent.copy() decorated.add_oxidation_state_by_element({Li: 1, O: -2})只有当猜测器被显式批准时才使用猜测结果且必须限制复杂度、保留全部候选赋值与假设、不得把第一次猜测当作实测电荷态。仓库对此给出了对应的工程约束在 composition_structure_validator.py 中--guess-oxidation-states是独立的显式开关且猜测被硬性限制为最多 6 种元素、100 个原子、返回前 20 个候选超过即报错默认不触发任何猜测见oxidation_state_guess_requested: False的输出字段与测试断言。_common.py中的structure_oxidation_summary只统计装饰情况guessed恒为False。无序结构有序化OrderDisorderedStructureTransformationfrom pymatgen.transformations.standard_transformations import ( OrderDisorderedStructureTransformation, ) transformation OrderDisorderedStructureTransformation() ranked transformation.apply_transformation( disordered, return_ranked_list20, )有序化可能组合爆炸。运行前必须验证占据率为有理数、所需超胞规模合理若静电排序需要氧化态则必须提供设定最大胞尺寸、site 数、候选数、运行时间、RAM 与磁盘上限说明排序模型与平局ties处理已知未返回候选数量时予以保留记录。排名第一的有序构型是模型依赖的结果不是唯一的基态——在没有收敛能量计算佐证前不得称为 ground state。EnumerateStructureTransformation 与 enumlibEnumerateStructureTransformation用于生成对称性不等价的有序构型依赖外部 enumlib 可执行程序enum.x与makestr.x。若干高级变换包括磁性有序都可能依赖枚举。enumlib 属于独立的原生代码执行必须按以下清单处理核实官方来源、版本、构建说明、许可证与哈希显式解析可执行文件路径审查精确的 argv 与工作目录隔离不可信输入强制胞大小、候选、CPU、RAM、磁盘与墙钟时间上限保留 stdout/stderr 与退出状态。不得自动安装或调用 enumlib。这与 SKILL.md 中可选工具enumlib、Bader、packmol、ffmpeg、Zeo 等都是原生/外部可执行程序在单独的显式调用前审查来源、许可证、argv、工作目录与资源限制的表述一致。掺杂与电荷平衡高级掺杂与电荷平衡变换编码了化学与静电假设。一个请求的掺杂元素并不能唯一定义被取代的主晶格物种/site氧化态浓度/超胞补偿空位或共掺杂剂有序化方式。执行前必须要求明确这些选择执行后报告每一个生成的候选并在每次变换后验证组成与净形式电荷。这也是原文档候选与输出上限一节所强调的绝不在耗尽预算后静默截断候选集并宣称穷尽。表面与 slabSlabTransformation与SlabGenerator需要显式的 Miller 指数、slab 厚度、真空厚度、shift/termination 与胞约化选择。必须限定终止面数量与生成结构数量记录厚度单位是 Å 还是单位平面数unit planes绝不覆盖体相父结构。表面能计算额外要求体相/slab 使用一致的方法、原子/参考态核算、表面积以及明确表面含一个还是两个等价表面。磁性有序MagOrderingTransformationMagOrderingTransformation使用建议磁矩并可能枚举有序构型。必须记录磁性物种及磁矩大小/单位通常 μB共线/非共线假设超胞与有序化约束若使用 enumlib 则记录其版本候选数量与排序方法。生成的磁性排布只是计算输入不是收敛的磁性基态。用 TransformedStructure 追踪历史pymatgen 的 alchemy 模块提供了内置的变换历史追踪from pymatgen.alchemy.materials import TransformedStructure from pymatgen.transformations.standard_transformations import ( SubstitutionTransformation, SupercellTransformation, ) tracked TransformedStructure(parent.copy(), []) tracked.append_transformation(SupercellTransformation([2, 2, 2])) tracked.append_transformation(SubstitutionTransformation({Na: K})) child tracked.final_structure history tracked.history但history 有用却不足以构成完整溯源。还必须额外存储输入与输出校验和警告流warning stream精确版本与依赖锁dependency lock用户意图与验收标准单位与坐标约定外部可执行程序元数据。存储格式应使用经过 schema 校验的严格 JSON禁止使用 pickle。仓库对严格 JSON有非常具体的落地_common.py中的load_strict_json在解析时拒绝重复键object_pairs_hook抛错并拒绝NaN/Infinityparse_constant抛错write_json_new使用排他创建path.open(x, ...)保证不覆盖既有文件artifact_manifest.py输出的清单里pickle_used恒为False测试 test_scripts.py 也专门验证了重复 JSON 键必须被拒绝test_strict_phase_json_rejects_duplicates。SKILL.md 第 12 条同样明确保留产物清单绝不使用 pickle 或加载不可信的通用对象图使用 schema 校验的 JSON 与显式构造器。六条可复用的溯源保留工作流工作流 1经过验证的本地派生validated local derivation对原始文件做哈希并验证hash and validate捕获解析器警告、单位、PBC、坐标模式、占据率/无序、氧化态、最小间距与 site 属性在 JSON 计划中定义变换与上限对副本应用变换验证子结构并对比该变换应满足的组成/site/晶格不变量写入新路径创建把 parent、plan 与 child 关联起来的产物清单。仓库提供了配套辅助脚本原文档给出的命令路径已转换为仓库根相对路径python skills/pymatgen/scripts/composition_structure_validator.py structure input.cif python skills/pymatgen/scripts/artifact_manifest.py \ --artifact input.cif --artifact transformed.json \ --workflow reviewed supercell derivation --output manifest.jsoncomposition_structure_validator.py的结构校验输出包含单位声明、晶格矩阵/体积/密度、PBC、坐标模式、占据率问题列表、氧化态汇总与最小周期距离当 site 数超过二次方检查上限--max-distance-sites默认 500绝对上限 1000时会显式警告最小间距检查因超过上限被跳过而不是悄悄略过。整个仓库测试用 NaCl 合成晶体NaCl 空间群 Pm-3m验证了这套校验的输出正确性见 test_scripts.py 的test_structure_tools_on_synthetic_crystal。工作流 2从无序到受限的有序候选将无序父结构保留为 JSON/CIF验证占据率求和与目标 site 分组定义超胞/胞大小与候选上限声明氧化态与排序模型若需要审查 enumlib 原生执行生成不超过批准数量的候选验证每个候选并保留映射/排名未经适当的收敛能量计算不得把排名第 1 的构型称为基态。工作流 3兼容的本地相图收集单一兼容方法/修正方案下的总能与组成为每个条目保留运行与修正溯源包含元素端点elemental endpoints与相关竞争相以energy_basis: total_per_entry写入严格 JSON运行python skills/pymatgen/scripts/phase_diagram_generator.py entries.json --analyze Li2O报告按 eV/atom 归一化的输出与数据集局限保留精确的 entries JSON 并记录其校验和。仓库中的 phase_diagram_generator.py 把这条工作流落实为离线工具顶层键必须是schema_version恒为1.0、energy_unit恒为eV、energy_basis恒为total_per_entry、provenance与entries任一不符即拒绝条目数上限默认 5000最大 10000每条目带独立的provenance报告同时给出每条目energy_eV_total、energy_eV_per_atom、formation_energy_eV_per_atom、energy_above_hull_eV_per_atom与on_computed_convex_hull并固定输出四条解释性限制hull 仅对该条目集与能量模型成立不得混用不兼容方法计算稳定性不是实验事实有限温度/压力/动力学/无序/不确定效应未包含。测试验证了该脚本的端到端行为Li/O2/Li2O 三个合成条目得到chemical_system Li-O、stable_entry_count 3且experimental_validity_established恒为False。工作流 4VASP 输入准备from pymatgen.io.vasp.sets import MPRelaxSet input_set MPRelaxSet( child, user_incar_settings{ENCUT: 600}, )在调用write_input()之前审查生成的每个文件与用户覆盖项user override核对 VASP/input-set 版本兼容性确认泛函、DFTU、磁性、自旋/SOC、k 点、smearing 与收敛设置仅在用户拥有 VASP 许可证的前提下处理 POTCAR写入新的计算目录。pymatgen 不运行 VASP也不替你确立收敛性。POTCAR 是 VASP 许可文件pymatgen 不随包分发本仓库 SKILL 也明确禁止重分发或扫描无关目录寻找它们。工作流 5能带结构链band-structure chain在文档化方法下弛豫并验证收敛把最终结构解析为新产物做一次兼容的静态计算以文档化的 k 路径与晶体学设定生成 line-mode 非自洽non-SCF计算解析时除非必需关闭投影本征值projected eigenvalues报告方法、结构、k 路径、自旋/SOC、费米能级约定以及与带隙一起的数值收敛信息。每个阶段必须链接到前一阶段的确切输出校验和不得静默复用陈旧结构或电荷密度。投影本征值可能消耗极端内存这也与 SKILL.md 中Vasprun(parse_projected_eigenFalse)的默认建议一致。工作流 6Materials Project 到本地分析用显式字段与 limit 先做一次有界的 dry-run 查询审查 CC BY 署名、引文与计算数据局限只在带--execute与指定的MP_API_KEY时才真正执行保留检索时间、查询、字段、来源origins、客户端版本与可用时的数据库版本在本地验证下载的结构在离线的新派生产物上做变换/分析。数据库对象是带溯源的计算输入不是实验事实。仓库的 mp_query.py 严格实现了这条流程默认输出完整披露计划endpoint、将访问的网络操作、认证方式为仅MP_API_KEY环境变量且绝不接受命令行传参、无隐式结果缓存、limit 与num_chunks1、限流与重试策略说明、数据许可与引文要求只有--execute才发起一次有界查询并要求新的--output执行时强制校验实装版本与验证快照一致并在结果中记录database_version与时间戳。测试test_mp_query_defaults_to_plan_and_never_reads_key与test_execute_without_named_key_fails_before_output_or_network分别验证了默认只出计划、不访问网络、不读密钥和缺少密钥时在输出或联网前即失败。候选与输出上限每个自动化工作流都必须有刹车无论哪条工作流都应设置如下硬性上限输入字节数与 site 数超胞行列式生成的候选/slab/有序构型数近邻、k 点、能带与投影数组规模JSON 记录数/字节数与绘图点数CPU、RAM、磁盘与墙钟时间。到达上限即停止并报告部分进度绝不静默截断候选集后将其宣称穷尽。这一设计原则在仓库 CLI 中处处可见_common.py定义了DEFAULT_MAX_INPUT_BYTES 50 MiB、DEFAULT_MAX_OUTPUT_BYTES 20 MiB、DEFAULT_MAX_SITES 10_000以及ABSOLUTE_MAX_*绝对上限mp_query.py限定--limit不超过 100phase_diagram_generator.py限定--analyze最多重复 20 次、绘图仅限 4 元素体系artifact_manifest.py拒绝超过 100 个产物或超过 2 GiB 总量并在输出 JSON 中显式声明network_accessed: False、directories_traversed: False、symlinks_followed: False等契约字段。小结把派生结构当成一等公民来治理本仓库 pymatgen skill 的核心立场可以浓缩为一句话每次结构变换都在创造科学假设必须像对待原始实验数据一样对待派生结构。落地时记住四件事永不就地修改父结构先 copy、应用、再用校验和断言每次变换记录完整元数据类名与版本、构造参数、父子校验和、占据/氧化态/电荷/自旋假设、候选排序方法、警告与外部程序使用对候选膨胀保持敬畏有序化、掺杂、表面、磁性枚举都可能组合爆炸所有维度都要有上限并在耗尽时明确报告用 strict JSON 而非 pickle 持久化配合仓库自带的 composition_structure_validator.py、artifact_manifest.py、phase_diagram_generator.py 与 mp_query.py即可把上述六条工作流固化为可复现、可审计、可引用的完整闭环。进一步可参考仓库内的配套文档SKILL.md技能总纲与验证快照、core_classes.md核心对象与单位/坐标约定、io_formats.md格式转换与表示损失、analysis_modules.md对称性/相图/能带分析与 materials_project_api.mdMP 查询、许可与限制。其中引用的 pymatgen transformations、alchemy、symmetry、surface、VASP sets API 及 enumlib 安装要求均为 pymatgen 官方公开文档本仓库于 2026-07-23 验证快照pymatgen2026.5.4、pymatgen-core2026.7.16、mp-api0.46.4下可复现文中全部代码路径。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考