pymatgen 是做什麼的？
使用 pymatgen 明確且保留來源地處理組成、分子、週期性結構、計算條目、對稱性、相圖、電子結構與電子結構程式碼檔案。將每一次的解析、轉換、對稱性指定、轉換與資料庫結果視為依賴方法與參數的結果。
此技能的 frontmatter 採用 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 版本、套件版本與產物雜湊。
必要工作流程
- 說明該物件是非週期性的
Molecule還是週期性的Structure；記錄晶格與週期性邊界條件。 - 說明單位。Pymatgen 通常使用 Å、度、eV、eV/atom、amu 與 g/cm³，但每個 API 的文件化合約具有權威性。
- 說明座標模式。
Structure的座標除非設定了coords_are_cartesian=True，否則為分數座標；Molecule的座標為笛卡爾座標。 - 檢查每個解析器警告。對於 CIF，請保留佔有率、位點合併、化學計量與修正警告；請勿默默接受修正。
- 報告無序/部分佔有率與氧化態標記。切勿隱式猜測氧化態。
- 在進行對稱性、鄰近、轉換、變換或熱力學分析之前，先執行驗證。
- 掃描對稱性容忍度，並在每次指定時報告以 Å 為單位的
symprec與以度為單位的angle_tolerance。 - 將轉換視為新的產物。保留輸入、參數、軟體版本、警告以及父/子項目的校驗和。
- 在轉換之前，識別表示法損失。僅寫入新路徑，並對科學相關屬性進行往返檢查。
- 僅從相容的總能與修正方案建構相圖。計算出的 Hull 取決於所提供的條目集合。
- 預設關閉所有資料庫存取。在顯式執行步驟之前，公開端點、過濾器、欄位、結果限制、快取行為、輸出、授權與引用。
- 保留產物清單。切勿使用 pickle 或載入未受信任的通用物件圖；請使用經過 schema 驗證的 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, # 度
)
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
一對多排序、摻雜、切面與磁性轉換可能呈組合式增長或呼叫可選的可執行檔。請限制候選項目、位點、超晶胞大小、執行時間與輸出數量。請參閱轉換與工作流程。
局部相圖
捆綁的生成器是離線的，且僅接受包含每個條目總 eV 與來源追溯的嚴格 JSON schema：
{
"schema_version": "1.0",
"energy_unit": "eV",
"energy_basis": "total_per_entry",
"provenance": {
"source": "經過審查的本地計算",
"method": "一個相容的能量/修正方案"
},
"entries": [
{
"entry_id": "local-Li",
"composition": "Li",
"energy_eV": -1.0,
"provenance": {"source": "計算清單 sha256:..."}
}
]
}
python scripts/phase_diagram_generator.py entries.json --analyze Li2O
必須提供元素端點與所有競爭相。請勿混合來自不同泛函、贗勢、磁態或修正慣例的原始能量。計算出的在 Hull 上方狀態並非實驗穩定性。
能帶結構、態密度、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
投影特徵值可能需要極大的記憶體。在解釋能隙或態密度之前，請驗證收斂性、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 初始化也會執行相容性/心跳中繼資料請求；規劃會揭露這些，停用平台詳細資訊使用者代理與本地資料庫版本通知日誌，並記錄返回的資料庫版本。摘要工作流程不會請求完整資料集快取下載。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— 嚴格的本地計算條目 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