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"
直接のピン留めはすべての推移的なホイールを固定するわけではありません。uv.lock、プラットフォーム、Pythonバージョン、パッケージバージョン、およびアーティファクトのハッシュを保存してください。
必須ワークフロー
- オブジェクトが非周期の
Moleculeであるか、周期のStructureであるかを明記し、格子と周期境界条件を記録します。 - 単位を明記します。Pymatgenは一般的にÅ、度、eV、eV/atom、amu、g/cm³を使用しますが、各APIの文書化された契約が優先されます。
- 座標モードを明記します。
Structureの座標は、coords_are_cartesian=Trueでない限り分数座標です。Moleculeの座標はデカルト座標です。 - すべてのパーサー警告を検査します。CIFの場合、占有率、サイトマージ、化学量論、補正の警告を保持し、修正を黙って受け入れないでください。
- 無秩序/部分占有率と酸化状態の装飾を報告します。酸化状態を暗黙的に推測しないでください。
- 対称性、近接、変換、変換、または熱力学解析の前に検証を実行します。
- 対称性許容値をスイープし、すべての割り当てで
symprec（Å単位）とangle_tolerance（度単位）を報告します。 - 変換は新しいアーティファクトとして扱います。入力、パラメータ、ソフトウェアバージョン、警告、親/子チェックサムを保存します。
- 変換前に表現の損失を特定します。新しいパスにのみ書き込み、科学的に関連するプロパティをラウンドトリップチェックします。
- 互換性のある全エネルギーと補正スキームからのみ状態図を構築します。計算されたハルは、提供されたエントリーセットに条件付きです。
- すべてのデータベースアクセスはデフォルトでオフにします。明示的な実行ステップの前に、エンドポイント、フィルター、フィールド、結果制限、キャッシュ動作、出力、ライセンス、および引用を開示します。
- アーティファクトマニフェストを保存します。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
1対多の秩序化、ドーピング、スラブ、および磁気変換は、組み合わせ的に拡大したり、オプションの実行可能ファイルを呼び出したりする可能性があります。候補、サイト、スーパーセルサイズ、ランタイム、および出力数を制限してください。変換とワークフローを参照してください。
ローカル状態図
バンドルされたジェネレーターはオフラインで、エントリごとの総eVと生成元を持つ厳密なJSONスキーマのみを受け入れます:
{
"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 を読み取ります。ユーザーのシェルまたはシークレットマネージャーを介して、その名前付き環境変数のみを指定します。キーを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 のみが、1つの制限付きサマリークエリを許可し、新しい出力を必要とします:
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— 新しいパスへの1ファイル変換。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