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"

直接指定したバージョンだけでは、すべての推移的なホイールは固定されません。uv.lock、プラットフォーム、Python バージョン、パッケージバージョン、成果物のハッシュを保持してください。

必須のワークフロー

1. オブジェクトが非周期的な Molecule か周期的な Structure かを明記し、格子と周期境界条件を記録します。
2. 単位を明記します。Pymatgen では通常、Å、度、eV、eV/atom、amu、 g/cm³ が使われますが、各 API のドキュメントに記載された仕様が優先されます。
3. 座標モードを明記します。coords_are_cartesian=True の場合を除き、 Structure の座標は分率座標です。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

順序付け、ドーピング、スラブ、磁性の一対多変換は、組み合わせ的に候補が増加したり、オプションの実行可能ファイルを呼び出したりする場合があります。候補数、サイト数、スーパーセルのサイズ、実行時間、出力数に上限を設けてください。変換とワークフローを参照してください。

ローカル相図

同梱の生成ツールはオフラインで動作し、エントリーあたりの総 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

参考資料

• コアクラス
• 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 FAQ と計算データに関する注意事項
• Materials Project 引用ページ
• pymatgen が推奨する公式チュートリアルシリーズ

エージェントの作業手順

1. 環境を確認します。 ライブラリのバージョン、単位、座標系、データ形式（FITS、CIF、HDF5、netCDF）を確認します。
2. 入力を特定します。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果に影響する値は推測せず、質問します。
3. まず小規模に実行します。 小さなグリッド、領域、またはサブセットで実行し、物理的に妥当かを確認します。
4. 上記の手順と参考情報に従って、タスク全体を実行します。
5. 結果を検証します。 単位と次元の整合性、保存則または既知の限界値、数値収束を確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未解決の不確実性を明記します。

このような場合	対応
結果が既知の物理的限界に反する場合	報告する前に、単位、境界条件、ソルバーの許容誤差を確認します。
これらの手順に記載された関数、フラグ、またはエンドポイントが、インストール済みのバージョンに存在しない場合	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して対応し、ユーザーに伝えます。APIをでっち上げてはいけません。
必須の入力、識別子、またはパラメーターが曖昧な場合	ユーザーに質問するか、実行前に仮定を明示します。

誠実性に関するルール

• 結果、パラメーター、識別子、引用、統計値を決して捏造しません。実行または検証できない場合は、その旨を明確に伝えます。
• すべての定量的な結果について、不確実性と数値許容誤差を報告します。
• ここに記載されたバージョン固有の情報は古くなっている可能性があるものとして扱い、インストール済みバージョンの公式ドキュメントで確認します。
• 費用が発生する、共有GPUやクラウドのクォータを消費する、個人データや患者データに触れる、または取り消せない操作を行う場合は、事前に確認を求めます。

関連スキル

• molfeat：SMILES文字列またはRDKit/datamolの分子を、計算機能を提供するmolfeat（0.11.0）を使用して数値特徴量に変換します。scikit-learn…
• protocolsio-integration：文書化されたREST v3/v4エンドポイントと公式MCPエンドポイントを使用してprotocols.ioのデータを読み取り、検証、エクスポートし、非実行可能な…