pymatgen

Pymatgen - Python Materials Genomics

概要

Pymatgen は、Materials Project を支える材料解析のための包括的な Python ライブラリです。結晶構造や分子の作成・解析・操作、相図や熱力学的性質の計算、電子構造（バンド構造、DOS）の解析、表面や界面の生成、そして Materials Project の計算済み材料データベースへのアクセスが可能です。さまざまな計算コードに由来する 100 以上のファイル形式をサポートしています。

このスキルを使用するタイミング

このスキルは、次のような場合に使用してください。

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

クイックスタートガイド

インストール

# Core pymatgen
uv pip install pymatgen

# With Materials Project API access
uv pip install pymatgen mp-api

# Optional dependencies for extended functionality
uv pip install pymatgen[analysis]  # Additional analysis tools
uv pip install pymatgen[vis]       # Visualization tools

基本的な構造操作

from pymatgen.core import Structure, Lattice

# Read structure from file (automatic format detection)
struct = Structure.from_file("POSCAR")

# Create structure from scratch
lattice = Lattice.cubic(3.84)
struct = Structure(lattice, ["Si", "Si"], [[0,0,0], [0.25,0.25,0.25]])

# Write to different format
struct.to(filename="structure.cif")

# Basic properties
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 との連携

# Set up API key
export MP_API_KEY="your_api_key_here"

from mp_api.client import MPRester

with MPRester() as mpr:
    # Get structure by material ID
    struct = mpr.get_structure_by_material_id("mp-149")

    # Search for materials
    materials = mpr.materials.summary.search(
        formula="Fe2O3",
        energy_above_hull=(0, 0.05)
    )

主な機能

1. 構造の作成と操作

さまざまな方法で構造を作成し、変換を行います。

ファイルから:

# Automatic format detection
struct = Structure.from_file("structure.cif")
struct = Structure.from_file("POSCAR")
mol = Molecule.from_file("molecule.xyz")

ゼロから:

from pymatgen.core import Structure, Lattice

# Using lattice parameters
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)

# From space group
struct = Structure.from_spacegroup(
    "Fm-3m",
    Lattice.cubic(3.5),
    ["Si"],
    [[0, 0, 0]]
)

変換:

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

# Create supercell
trans = SupercellTransformation([[2,0,0],[0,2,0],[0,0,2]])
supercell = trans.apply_transformation(struct)

# Substitute elements
trans = SubstitutionTransformation({"Fe": "Mn"})
new_struct = trans.apply_transformation(struct)

# Get primitive cell
trans = PrimitiveCellTransformation()
primitive = trans.apply_transformation(struct)

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

2. ファイル形式の変換

自動形式判定を用いて、100 以上のファイル形式の間で変換を行います。

簡易メソッドを使用する場合:

# Read any format
struct = Structure.from_file("input_file")

# Write to any format
struct.to(filename="output.cif")
struct.to(filename="POSCAR")
struct.to(filename="output.xyz")

変換スクリプトを使用する場合:

# Single file conversion
python scripts/structure_converter.py POSCAR structure.cif

# Batch conversion
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)

# Get space group information
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()}")

# Get conventional/primitive cells
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)  # Neighbors of site 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} Å")

解析スクリプトを使用する場合:

# Comprehensive analysis
python scripts/structure_analyzer.py POSCAR --symmetry --neighbors

# Export results
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

# Get entries from Materials Project
with MPRester() as mpr:
    entries = mpr.get_entries_in_chemsys("Li-Fe-O")

# Build phase diagram
pd = PhaseDiagram(entries)

# Check stability
from pymatgen.core import Composition
comp = Composition("LiFeO2")

# Find entry for composition
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:
            # Get decomposition
            decomp = pd.get_decomposition(comp)
            print("Decomposes to:", decomp)

# Plot
plotter = PDPlotter(pd)
plotter.show()

相図スクリプトを使用する場合:

# Generate phase diagram
python scripts/phase_diagram_generator.py Li-Fe-O --output li_fe_o.png

# Analyze specific composition
python scripts/phase_diagram_generator.py Li-Fe-O --analyze "LiFeO2" --show

リファレンス: 詳細な例については references/analysis_modules.md（Phase Diagrams セクション）および references/transformations_workflows.md（Workflow 2）を参照してください。

5. 電子構造解析

バンド構造、状態密度、電子的性質を解析します。

バンド構造:

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

# Read from VASP calculation
vasprun = Vasprun("vasprun.xml")
bs = vasprun.get_band_structure()

# Analyze
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()}")

# Plot
plotter = BSPlotter(bs)
plotter.save_plot("band_structure.png")

状態密度:

from pymatgen.electronic_structure.plotter import DosPlotter

dos = vasprun.complete_dos

# Get element-projected 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")

# Plot
plotter = DosPlotter()
plotter.add_dos("Total DOS", dos)
plotter.show()

リファレンス: references/analysis_modules.md（Electronic Structure セクション）および references/io_formats.md（VASP セクション）を参照してください。

6. 表面と界面の解析

スラブを生成し、表面を解析し、界面を研究します。

スラブの生成:

from pymatgen.core.surface import SlabGenerator

# Generate slabs for specific Miller index
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()

# Write slabs
for i, slab in enumerate(slabs):
    slab.to(filename=f"slab_{i}.cif")

Wulff 形状の構築:

from pymatgen.analysis.wulff import WulffShape

# Define surface energies
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)

# Find sites
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'])}")

# Add adsorbate
adsorbate = Molecule("O", [[0, 0, 0]])
ads_struct = asf.add_adsorbate(adsorbate, ads_sites["ontop"][0])

リファレンス: references/analysis_modules.md（Surface and Interface セクション）および references/transformations_workflows.md（Workflows 3 and 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:
    # Search by formula
    materials = mpr.materials.summary.search(formula="Fe2O3")

    # Search by chemical system
    materials = mpr.materials.summary.search(chemsys="Li-Fe-O")

    # Filter by properties
    materials = mpr.materials.summary.search(
        chemsys="Li-Fe-O",
        energy_above_hull=(0, 0.05),  # Stable/metastable
        band_gap=(1.0, 3.0)            # Semiconducting
    )

    # Get structure
    struct = mpr.get_structure_by_material_id("mp-149")

    # Get band structure
    bs = mpr.get_bandstructure_by_material_id("mp-149")

    # Get entries for phase diagram
    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

# Relaxation
relax = MPRelaxSet(struct)
relax.write_input("./relax_calc")

# Static calculation
static = MPStaticSet(struct)
static.write_input("./static_calc")

# Band structure (non-self-consistent)
nscf = MPNonSCFSet(struct, mode="line")
nscf.write_input("./bandstructure_calc")

# Custom parameters
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)

# Get peaks
for peak in pattern.hkls:
    print(f"2θ = {peak['2theta']:.2f}°, hkl = {peak['hkl']}")

pattern.plot()

弾性特性:

from pymatgen.analysis.elasticity import ElasticTensor

# From elastic tensor matrix
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

# Enumerate magnetic orderings
trans = MagOrderingTransformation({"Fe": 5.0})
mag_structs = trans.apply_transformation(struct, return_ranked_list=True)

# Get lowest energy magnetic structure
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: Transformations フレームワークと一般的なワークフロー

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

一般的なワークフロー

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

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

# Generate doped structures
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)

    # Generate VASP inputs
    vasp_input = MPRelaxSet(doped_struct)
    vasp_input.write_input(f"./calcs/Fe_{dopant}")

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

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

# 2. Static (after relaxation)
relaxed = Structure.from_file("1_relax/CONTCAR")
static = MPStaticSet(relaxed)
static.write_input("./2_static")

# 3. Band structure (non-self-consistent)
nscf = MPNonSCFSet(relaxed, mode="line")
nscf.write_input("./3_bandstructure")

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

表面エネルギーの計算

# 1. Get bulk energy
bulk_vasprun = Vasprun("bulk/vasprun.xml")
bulk_E_per_atom = bulk_vasprun.final_energy / len(bulk)

# 2. Generate and calculate slabs
slabgen = SlabGenerator(bulk, (1,1,1), 10, 15)
slab = slabgen.get_slabs()[0]

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

# 3. Calculate surface energy (after calculation)
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  # Convert eV/Ų to 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"

構造の読み込み失敗: ファイル形式と構文を確認してください

# Try explicit format specification
struct = Structure.from_file("file.txt", fmt="cif")

対称性解析が失敗する: 構造に数値精度の問題がある可能性があります

# Increase tolerance
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 を使用する場合は、mp-api パッケージを使用してください（レガシーの pymatgen.ext.matproj とは別物です）。

要件：

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