alterlab-pymatgen

Pymatgen - Python Materials Genomics

概要

Pymatgen は、Materials Project を支える包括的な材料解析用 Python ライブラリです。結晶構造や分子の作成、解析、操作、状態図や熱力学的特性の計算、電子構造（バンド構造、DOS）の解析、表面や界面の生成、Materials Project データベースへのアクセスができます。さまざまな計算コードの 100 種類以上のファイル形式に対応しています。

このスキルを使用する場合

次のような場合に使用します：

• 材料科学で結晶構造や分子系を扱う場合
• 構造ファイル形式（CIF、POSCAR、XYZ など）を相互に変換する場合
• 対称性、空間群、配位環境を解析する場合
• 状態図を計算したり、熱力学的安定性を評価したりする場合
• 電子構造（バンドギャップ、DOS、バンド構造）を解析する場合
• 表面やスラブを生成したり、界面を研究したりする場合
• Materials Project データベースにプログラムからアクセスする場合
• ハイスループット計算ワークフローを設定する場合
• VASP、Gaussian、Quantum ESPRESSO、その他の計算コードを扱う場合

対象外

シナリオ	代わりに使用
小さな有機分子 — SMILES、フィンガープリント、記述子、部分構造検索	alterlab-rdkit
管理されたクラウド量子化学サービスでの DFT 実行／配座探索／pKa 計算	alterlab-rowan
タンパク質やリガンドの古典的分子動力学（OpenMM、軌跡）	alterlab-molecular-dynamics
分子の基底状態を求める変分量子回路（VQE）	alterlab-pennylane

クイックスタート

uv pip install pymatgen                # core (Python >= 3.11)
uv pip install pymatgen mp-api         # + Materials Project API access
uv pip install "pymatgen[optional]"    # extra analysis deps (phonopy, seekpath, ase, ...)
uv pip install "pymatgen[vis]"         # VTK structure visualization

from pymatgen.core import Structure, Lattice

struct = Structure.from_file("POSCAR")        # auto format detection
struct.to(filename="structure.cif")           # write any format
print(struct.composition.reduced_formula)
print(struct.get_space_group_info())
print(f"{struct.density:.2f} g/cm³")

export MP_API_KEY="your_api_key_here"   # for Materials Project access

主な機能（振り分け）

各機能のコピーして使えるコードブロックは references/core_examples.md にあり、詳しいモジュールのドキュメントは以下に示すリファレンスにあります。

1. 構造の作成と操作 — ファイルからの作成、一からの作成（格子パラメーターまたは空間群）、変換（スーパーセル、置換、原始セル）。→ core_classes.md
2. ファイル形式の変換 — from_file()／to() に加え、単一／一括変換用の scripts/structure_converter.py。→ io_formats.md
3. 構造解析と対称性 — SpacegroupAnalyzer、CrystalNN、および scripts/structure_analyzer.py。→ analysis_modules.md
4. 状態図と熱力学 — PhaseDiagram、凸包からのエネルギー差、分解、および scripts/phase_diagram_generator.py。→ analysis_modules.md、transformations_workflows.md
5. 電子構造 — Vasprun によるバンド構造と DOS、バンドギャップ、金属性。→ analysis_modules.md、io_formats.md
6. 表面と界面 — SlabGenerator、WulffShape、AdsorbateSiteFinder。→ analysis_modules.md、transformations_workflows.md
7. Materials Project へのアクセス — プロパティーフィルターによる MPRester の検索と取得。→ materials_project_api.md
8. 計算ワークフローの設定 — VASP 入力セット（MPRelaxSet、MPStaticSet、MPNonSCFSet）、Gaussian、Quantum ESPRESSO。→ io_formats.md、transformations_workflows.md
9. 高度な解析 — XRD パターン、弾性テンソル、磁気秩序。→ analysis_modules.md

複数ステップの実践例（ハイスループット生成、バンド構造パイプライン、表面エネルギー）：references/common_workflows_code.md。

同梱リソース

スクリプト（scripts/）

• structure_converter.py：構造ファイル形式を相互に変換します（一括変換＋自動検出）。使用方法：python scripts/structure_converter.py POSCAR structure.cif
• structure_analyzer.py：対称性、配位、格子パラメーター、距離行列を解析します。使用方法：python scripts/structure_analyzer.py structure.cif --symmetry --neighbors
• phase_diagram_generator.py：Materials Project から状態図を生成し、安定性を解析します。使用方法：python scripts/phase_diagram_generator.py Li-Fe-O --analyze "LiFeO2"

すべてのスクリプトで詳細なヘルプを利用できます。例：python scripts/structure_converter.py --help

References (references/)

• core_examples.md：9 つすべてのコア機能のコピー＆ペースト可能なコード
• common_workflows_code.md：複数ステップのワークフローを実行するコード例
• core_classes.md：Element、Structure、Lattice、Molecule、Composition クラス
• io_formats.md：ファイル形式のサポートとコード連携（VASP、Gaussian など）
• analysis_modules.md：相図、表面、電子構造、対称性
• materials_project_api.md：Materials Project API の完全ガイド
• transformations_workflows.md：変換フレームワークとよく使われる 10 種類のワークフロー

ベストプラクティス

構造：自動形式検出を使用します。不変な構造には IStructure を優先します。SpacegroupAnalyzer で基本単位胞に縮約します。原子の重なりや異常な結合長がないか検証します。ファイル I/O：from_file()／to() を優先します。形式検出に失敗する場合は形式を指定します。バージョン間で安全に保存するには as_dict()／from_dict() を使用します。MP API：常にコンテキストマネージャーを使用します。クエリをまとめて実行し、結果をキャッシュし、プロパティで絞り込みます。ワークフロー：INCAR の手動設定より入力セットを優先します。収束を確認し、来歴を追跡できるよう変換を記録します。パフォーマンス：基本単位胞を使用します。近傍探索のカットオフを制限し、可能であれば並列化します。

単位と規約

長さは Å、エネルギーは eV、角度は度、磁気モーメントは μB、時間は fs です。 pymatgen.core.units で変換できます。

連携

ASE、Phonopy、BoltzTraP、Atomate/Fireworks、AiiDA、Zeo++、OpenBabel と連携します。

トラブルシューティング

• インポートエラー：uv pip install "pymatgen[optional,vis]"（[analysis] という追加機能はありません）
• API キーが見つからない：export MP_API_KEY="your_key_here"
• 構造の読み込みエラー：形式を明示的に指定してみてください。例：Structure.from_file("file.txt", fmt="cif")
• 対称性解析の失敗：許容値を大きくしてみてください。例：SpacegroupAnalyzer(struct, symprec=0.1)

追加リソース

ドキュメント：https://pymatgen.org/ · Materials Project：https://materialsproject.org/ · GitHub：https://github.com/materialsproject/pymatgen · フォーラム：https://matsci.org/ · サンプルノートブック：https://github.com/materialsvirtuallab/matgenb

バージョンに関する注意

pymatgen 2024.x 以降を対象としています（2026-09 時点の最新バージョンは 2026.9.x、カレンダーバージョニング）。2026 年以降、pymatgen ディストリビューションは pymatgen-core を基盤とする薄いパッケージになりました。インポート（pymatgen.core、pymatgen.io.vasp、…）に変更はありません。Materials Project API には、従来の pymatgen.ext.matproj クライアントではなく、mp-api パッケージ（最新バージョン 0.46.x、from mp_api.client import MPRester）を使用してください。要件：Python ≥ 3.11、pymatgen ≥ 2024.x、Materials Project へのアクセスには mp-api が必要です。

AlterLab Academic Skills スイートの一部です。