Pymatgen - Python Materials Genomics

概要

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

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

以下のような場合にこのスキルを使用してください：

• 材料科学における結晶構造や分子系を扱う場合
• 構造ファイル形式（CIF、POSCAR、XYZ等）間の変換
• 対称性、空間群、配位環境の解析
• 相図の計算や熱力学的安定性の評価
• 電子構造データの解析（バンドギャップ、DOS、バンド構造）
• 表面、スラブ、インターフェースの生成と研究
• プログラムによるMaterials Projectデータベースのアクセス
• ハイスループット計算ワークフローのセットアップ
• 拡散、磁性、機械的性質の解析
• VASP、Gaussian、Quantum ESPRESSO等の計算コードの使用

クイックスタートガイド

インストール

# Pymatgenコア
uv pip install pymatgen

# Materials Project APIアクセス対応
uv pip install pymatgen mp-api

# 拡張機能用のオプション依存関係
uv pip install pymatgen[analysis]  # 追加の解析ツール
uv pip install pymatgen[vis]       # ビジュアライゼーションツール

基本的な構造操作

from pymatgen.core import Structure, Lattice

# ファイルから構造を読み込む（自動形式検出）
struct = Structure.from_file("POSCAR")

# スクラッチから構造を作成
lattice = Lattice.cubic(3.84)
struct = Structure(lattice, ["Si", "Si"], [[0,0,0], [0.25,0.25,0.25]])

# 別の形式で出力
struct.to(filename="structure.cif")

# 基本的な性質
print(f"Formula: {struct.composition.reduced_formula}")
print(f"Space group: {struct.get_space_group_info()}")
print(f"Density: {struct.density:.2f} g/cm³")

Materials Projectとの統合

# APIキーの設定
export MP_API_KEY="your_api_key_here"

from mp_api.client import MPRester

with MPRester() as mpr:
    # 材料IDから構造を取得
    struct = mpr.get_structure_by_material_id("mp-149")

    # 材料を検索
    materials = mpr.materials.summary.search(
        formula="Fe2O3",
        energy_above_hull=(0, 0.05)
    )

コア機能

1. 構造の作成と操作

様々な方法で構造を作成し、変換を実行します。

ファイルから：

# 自動形式検出
struct = Structure.from_file("structure.cif")
struct = Structure.from_file("POSCAR")
mol = Molecule.from_file("molecule.xyz")

スクラッチから：

from pymatgen.core import Structure, Lattice

# 格子パラメータを使用
lattice = Lattice.from_parameters(a=3.84, b=3.84, c=3.84,
                                  alpha=120, beta=90, gamma=60)
coords = [[0, 0, 0], [0.75, 0.5, 0.75]]
struct = Structure(lattice, ["Si", "Si"], coords)

# 空間群から
struct = Structure.from_spacegroup(
    "Fm-3m",
    Lattice.cubic(3.5),
    ["Si"],
    [[0, 0, 0]]
)

変換：

from pymatgen.transformations.standard_transformations import (
    SupercellTransformation,
    SubstitutionTransformation,
    PrimitiveCellTransformation
)

# スーパーセルを作成
trans = SupercellTransformation([[2,0,0],[0,2,0],[0,0,2]])
supercell = trans.apply_transformation(struct)

# 元素を置換
trans = SubstitutionTransformation({"Fe": "Mn"})
new_struct = trans.apply_transformation(struct)

# プリミティブセルを取得
trans = PrimitiveCellTransformation()
primitive = trans.apply_transformation(struct)

リファレンス： Structure、Lattice、Molecule及び関連クラスの包括的なドキュメントについては references/core_classes.md を参照してください。

2. ファイル形式の変換

100以上のファイル形式間の変換に対応し、自動形式検出があります。

便利なメソッドの使用：

# 任意の形式を読み込む
struct = Structure.from_file("input_file")

# 任意の形式で出力
struct.to(filename="output.cif")
struct.to(filename="POSCAR")
struct.to(filename="output.xyz")

変換スクリプトの使用：

# 単一ファイルの変換
python scripts/structure_converter.py POSCAR structure.cif

# バッチ変換
python scripts/structure_converter.py *.cif --output-dir ./poscar_files --format poscar

リファレンス： サポートされている全ての形式とコード統合の詳細については references/io_formats.md を参照してください。

3. 構造解析と対称性

対称性、配位、その他の性質について構造を解析します。

対称性解析：

from pymatgen.symmetry.analyzer import SpacegroupAnalyzer

sga = SpacegroupAnalyzer(struct)

# 空間群情報を取得
print(f"Space group: {sga.get_space_group_symbol()}")
print(f"Number: {sga.get_space_group_number()}")
print(f"Crystal system: {sga.get_crystal_system()}")

# 慣用セルとプリミティブセルを取得
conventional = sga.get_conventional_standard_structure()
primitive = sga.get_primitive_standard_structure()

配位環境：

from pymatgen.analysis.local_env import CrystalNN

cnn = CrystalNN()
neighbors = cnn.get_nn_info(struct, n=0)  # サイト0の近傍

print(f"Coordination number: {len(neighbors)}")
for neighbor in neighbors:
    site = struct[neighbor['site_index']]
    print(f"  {site.species_string} at {neighbor['weight']:.3f} Å")

解析スクリプトの使用：

# 包括的な解析
python scripts/structure_analyzer.py POSCAR --symmetry --neighbors

# 結果をエクスポート
python scripts/structure_analyzer.py structure.cif --symmetry --export json

リファレンス： 全ての解析機能の詳細については references/analysis_modules.md を参照してください。

4. 相図と熱力学

相図を構築し、熱力学的安定性を解析します。

相図の構築：

from mp_api.client import MPRester
from pymatgen.analysis.phase_diagram import PhaseDiagram, PDPlotter

# Materials Projectからエントリを取得
with MPRester() as mpr:
    entries = mpr.get_entries_in_chemsys("Li-Fe-O")

# 相図を構築
pd = PhaseDiagram(entries)

# 安定性をチェック
from pymatgen.core import Composition
comp = Composition("LiFeO2")

# 組成のエントリを検索
for entry in entries:
    if entry.composition.reduced_formula == comp.reduced_formula:
        e_above_hull = pd.get_e_above_hull(entry)
        print(f"Energy above hull: {e_above_hull:.4f} eV/atom")

        if e_above_hull > 0.001:
            # 分解を取得
            decomp = pd.get_decomposition(comp)
            print("Decomposes to:", decomp)

# プロット
plotter = PDPlotter(pd)
plotter.show()

相図生成スクリプトの使用：

# 相図を生成
python scripts/phase_diagram_generator.py Li-Fe-O --output li_fe_o.png

# 特定の組成を解析
python scripts/phase_diagram_generator.py Li-Fe-O --analyze "LiFeO2" --show

リファレンス： 詳細な例については references/analysis_modules.md（相図セクション）と references/transformations_workflows.md（ワークフロー2）を参照してください。

5. 電子構造解析

バンド構造、状態密度、および電子特性を解析します。

バンド構造：

from pymatgen.io.vasp import Vasprun
from pymatgen.electronic_structure.plotter import BSPlotter

# VASP計算から読み込む
vasprun = Vasprun("vasprun.xml")
bs = vasprun.get_band_structure()

# 解析
band_gap = bs.get_band_gap()
print(f"Band gap: {band_gap['energy']:.3f} eV")
print(f"Direct: {band_gap['direct']}")
print(f"Is metal: {bs.is_metal()}")

# プロット
plotter = BSPlotter(bs)
plotter.save_plot("band_structure.png")

状態密度：

from pymatgen.electronic_structure.plotter import DosPlotter

dos = vasprun.complete_dos

# 元素射影DOSを取得
element_dos = dos.get_element_dos()
for element, element_dos_obj in element_dos.items():
    print(f"{element}: {element_dos_obj.get_gap():.3f} eV")

# プロット
plotter = DosPlotter()
plotter.add_dos("Total DOS", dos)
plotter.show()

リファレンス： references/analysis_modules.md（電子構造セクション）と references/io_formats.md（VASPセクション）を参照してください。

6. 表面とインターフェース解析

スラブを生成し、表面を解析し、インターフェースを研究します。

スラブの生成：

from pymatgen.core.surface import SlabGenerator

# 特定のミラー指数のスラブを生成
slabgen = SlabGenerator(
    struct,
    miller_index=(1, 1, 1),
    min_slab_size=10.0,      # Å
    min_vacuum_size=10.0,    # Å
    center_slab=True
)

slabs = slabgen.get_slabs()

# スラブを出力
for i, slab in enumerate(slabs):
    slab.to(filename=f"slab_{i}.cif")

Wulff形状の構築：

from pymatgen.analysis.wulff import WulffShape

# 表面エネルギーを定義
surface_energies = {
    (1, 0, 0): 1.0,
    (1, 1, 0): 1.1,
    (1, 1, 1): 0.9,
}

wulff = WulffShape(struct.lattice, surface_energies)
print(f"Surface area: {wulff.surface_area:.2f} Ų")
print(f"Volume: {wulff.volume:.2f} ų")

wulff.show()

吸着サイトの検索：

from pymatgen.analysis.adsorption import AdsorbateSiteFinder
from pymatgen.core import Molecule

asf = AdsorbateSiteFinder(slab)

# サイトを検索
ads_sites = asf.find_adsorption_sites()
print(f"On-top sites: {len(ads_sites['ontop'])}")
print(f"Bridge sites: {len(ads_sites['bridge'])}")
print(f"Hollow sites: {len(ads_sites['hollow'])}")

# 吸着物を追加
adsorbate = Molecule("O", [[0, 0, 0]])
ads_struct = asf.add_adsorbate(adsorbate, ads_sites["ontop"][0])

リファレンス： references/analysis_modules.md（表面とインターフェースセクション）と references/transformations_workflows.md（ワークフロー3と9）を参照してください。

7. Materials Projectデータベースアクセス

プログラムによってMaterials Projectデータベースにアクセスします。

セットアップ：

1. https://next-gen.materialsproject.org/ からAPIキーを取得します
2. 環境変数を設定します：export MP_API_KEY="your_key_here"

検索と取得：

from mp_api.client import MPRester

with MPRester() as mpr:
    # 化学式で検索
    materials = mpr.materials.summary.search(formula="Fe2O3")

    # 化学系で検索
    materials = mpr.materials.summary.search(chemsys="Li-Fe-O")

    # 性質でフィルタリング
    materials = mpr.materials.summary.search(
        chemsys="Li-Fe-O",
        energy_above_hull=(0, 0.05),  # 安定/準安定
        band_gap=(1.0, 3.0)            # 半導体
    )

    # 構造を取得
    struct = mpr.get_structure_by_material_id("mp-149")

    # バンド構造を取得
    bs = mpr.get_bandstructure_by_material_id("mp-149")

    # 相図用のエントリを取得
    entries = mpr.get_entries_in_chemsys("Li-Fe-O")

リファレンス： 包括的なAPIドキュメントと例については references/materials_project_api.md を参照してください。

8. 計算ワークフローのセットアップ

様々な電子構造コード用の計算をセットアップします。

VASP入力の生成：

from pymatgen.io.vasp.sets import MPRelaxSet, MPStaticSet, MPNonSCFSet

# 緩和計算
relax = MPRelaxSet(struct)
relax.write_input("./relax_calc")

# 静的計算
static = MPStaticSet(struct)
static.write_input("./static_calc")

# バンド構造計算（非自己無撞着）
nscf = MPNonSCFSet(struct, mode="line")
nscf.write_input("./bandstructure_calc")

# カスタムパラメータ
custom = MPRelaxSet(struct, user_incar_settings={"ENCUT": 600})
custom.write_input("./custom_calc")

他のコード：

# Gaussian
from pymatgen.io.gaussian import GaussianInput

gin = GaussianInput(
    mol,
    functional="B3LYP",
    basis_set="6-31G(d)",
    route_parameters={"Opt": None}
)
gin.write_file("input.gjf")

# Quantum ESPRESSO
from pymatgen.io.pwscf import PWInput

pwin = PWInput(struct, control={"calculation": "scf"})
pwin.write_file("pw.in")

リファレンス： references/io_formats.md（電子構造コードI/Oセクション）と references/transformations_workflows.md を参照してください。

9. 高度な解析

回折パターン：

from pymatgen.analysis.diffraction.xrd import XRDCalculator

xrd = XRDCalculator()
pattern = xrd.get_pattern(struct)

# ピークを取得
for peak in pattern.hkls:
    print(f"2θ = {peak['2theta']:.2f}°, hkl = {peak['hkl']}")

pattern.plot()

弾性特性：

from pymatgen.analysis.elasticity import ElasticTensor

# 弾性テンソル行列から
elastic_tensor = ElasticTensor.from_voigt(matrix)

print(f"Bulk modulus: {elastic_tensor.k_voigt:.1f} GPa")
print(f"Shear modulus: {elastic_tensor.g_voigt:.1f} GPa")
print(f"Young's modulus: {elastic_tensor.y_mod:.1f} GPa")

磁気秩序：

from pymatgen.transformations.advanced_transformations import MagOrderingTransformation

# 磁気秩序を列挙
trans = MagOrderingTransformation({"Fe": 5.0})
mag_structs = trans.apply_transformation(struct, return_ranked_list=True)

# 最低エネルギーの磁気構造を取得
lowest_energy_struct = mag_structs[0]['structure']

リファレンス： 包括的な解析モジュールのドキュメントについては references/analysis_modules.md を参照してください。

バンドルされたリソース

スクリプト（scripts/）

一般的なタスク用の実行可能Pythonスクリプト：

• 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/script_name.py --help

リファレンス（references/）

必要に応じてコンテキストに読み込まれる包括的なドキュメント：

• 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: 変換フレームワークと一般的なワークフロー

特定のモジュールやワークフローに関する詳細情報が必要な場合は、リファレンスを読み込んでください。

一般的なワークフロー

ハイスループット構造生成

from pymatgen.transformations.standard_transformations import SubstitutionTransformation
from pymatgen.io.vasp.sets import MPRelaxSet

# ドープ構造を生成
base_struct = Structure.from_file("POSCAR")
dopants = ["Mn", "Co", "Ni", "Cu"]

for dopant in dopants:
    trans = SubstitutionTransformation({"Fe": dopant})
    doped_struct = trans.apply_transformation(base_struct)

    # VASP入力を生成
    vasp_input = MPRelaxSet(doped_struct)
    vasp_input.write_input(f"./calcs/Fe_{dopant}")

バンド構造計算ワークフロー

# 1. 緩和
relax = MPRelaxSet(struct)
relax.write_input("./1_relax")

# 2. 静的計算（緩和後）
relaxed = Structure.from_file("1_relax/CONTCAR")
static = MPStaticSet(relaxed)
static.write_input("./2_static")

# 3. バンド構造（非自己無撞着）
nscf = MPNonSCFSet(relaxed, mode="line")
nscf.write_input("./3_bandstructure")

# 4. 解析
from pymatgen.io.vasp import Vasprun
vasprun = Vasprun("3_bandstructure/vasprun.xml")
bs = vasprun.get_band_structure()
bs.get_band_gap()

表面エネルギー計算

# 1. バルクエネルギーを取得
bulk_vasprun = Vasprun("bulk/vasprun.xml")
bulk_E_per_atom = bulk_vasprun.final_energy / len(bulk)

# 2. スラブを生成して計算
slabgen = SlabGenerator(bulk, (1,1,1), 10, 15)
slab = slabgen.get_slabs()[0]

MPRelaxSet(slab).write_input("./slab_calc")

# 3. 表面エネルギーを計算（計算後）
slab_vasprun = Vasprun("slab_calc/vasprun.xml")
E_surf = (slab_vasprun.final_energy - len(slab) * bulk_E_per_atom) / (2 * slab.surface_area)
E_surf *= 16.021766  # eV/ŲをJ/m²に変換

その他のワークフロー： 10の詳細なワークフロー例については references/transformations_workflows.md を参照してください。

ベストプラクティス

構造の取り扱い

1. 自動形式検出を使用: Structure.from_file()はほとんどの形式に対応
2. 不変構造を優先: 構造が変更されるべきでない場合は IStructure を使用
3. 対称性をチェック: SpacegroupAnalyzer を使用してプリミティブセルに縮小
4. 構造を検証: 重なった原子や不合理な結合長をチェック

ファイルI/O

1. 便利なメソッドを使用: from_file() と to() が推奨
2. 形式を明示的に指定: 自動検出が失敗する場合
3. 例外を処理: ファイルI/Oをtry-exceptブロックでラップ
4. シリアライゼーション使用: バージョン安全な保存に as_dict()/from_dict() を使用

Materials Project API

1. コンテキストマネージャを使用: 常に with MPRester() as mpr: を使用
2. バッチクエリ: 複数の項目を一度にリクエスト
3. 結果をキャッシュ: よく使うデータはローカルに保存
4. 効果的にフィルタリング: プロパティフィルタを使用してデータ転送を削減

計算ワークフロー

1. 入力セットを使用: 手動のINCARではなく MPRelaxSet、MPStaticSet を優先
2. 収束をチェック: 常に計算が収束したことを確認
3. 変換を追跡: プロバナンスのために TransformedStructure を使用
4. 計算を整理: 明確なディレクトリ構造を使用

パフォーマンス

1. 対称性を縮小: 可能な場合はプリミティブセルを使用
2. 近傍検索を制限: 合理的なカットオフ半径を指定
3. 適切なメソッドを使用: 異なる解析ツールは異なる速度/精度トレードオフがあります
4. 可能な場合は並列化: 多くの操作を並列化できます

単位と規約

Pymatgenは全体を通して原子単位を使用します：

• 長さ：オングストローム（Å）
• エネルギー：電子ボルト（eV）
• 角度：度（°）
• 磁気モーメント：ボーア磁子（μB）
• 時間：フェムト秒（fs）

必要に応じて pymatgen.core.units を使用して単位を変換します。

他のツールとの統合

Pymatgenは以下とシームレスに統合されます：

• ASE（Atomic Simulation Environment）
• Phonopy（フォノン計算）
• BoltzTraP（輸送特性）
• Atomate/Fireworks（ワークフロー管理）
• AiiDA（プロバナンス追跡）
• Zeo++（細孔解析）
• OpenBabel（分子変換）

トラブルシューティング

インポートエラー：足りない依存関係をインストール

uv pip install pymatgen[analysis,vis]

APIキーが見つからない：MP_API_KEY環境変数を設定

export MP_API_KEY="your_key_here"

構造読み込み失敗：ファイル形式と構文をチェック

# 明示的に形式を指定してみる
struct = Structure.from_file("file.txt", fmt="cif")

対称性解析が失敗：構造が数値精度の問題を持っている可能性

# 許容度を増加
from pymatgen.symmetry.analyzer import SpacegroupAnalyzer
sga = SpacegroupAnalyzer(struct, symprec=0.1)

追加リソース

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

バージョン情報

このスキルはpymatgen 2024.x以降向けに設計されています。Materials Project APIについては、legacy pymatgen.ext.matproj から分離された mp-api パッケージを使用してください。

要件：

• Python 3.10以上
• pymatgen >= 2023.x
• mp-api（Materials Projectアクセス用）