make_kpoints.py 技術ドキュメント

プログラムの動作

make_kpoints.py は、Crystallographic Information File (CIF) 形式の結晶構造データから、第一原理計算ソフトウェアVASPでバンド構造計算を行うためのKPOINTSファイルを自動生成するPythonスクリプトです。

プログラムの目的

このプログラムの主要な目的は、VASPユーザーが手動でKPOINTSファイルを作成する手間を省き、ブリルアンゾーン内の正確な高対称性経路に沿ったK点グリッドを効率的かつ正確に生成することです。

主な機能

  1. CIFファイルの読み込み: 入力としてCIFファイルを解析し、結晶構造情報を抽出します。

  2. 結晶構造の標準化と対称性解析: pymatgen ライブラリを用いて結晶の対称性を検出し、必要に応じて構造を標準的なプリミティブセルに変換します。これにより、高対称性経路の特定が容易になります。

  3. 高対称性K点経路の生成: 結晶のブラベー格子タイプに基づき、第一ブリルアンゾーン内の高対称点とそれらをつなぐ経路を自動的に決定します。Setyawan-Curtarolo、Latimer-Munro、Hinumaなど、複数の高対称性パスの慣例をサポートします。

  4. K点座標の丸め: 生成されたK点座標の浮動小数点値を、指定された最大分母までの分数表現に丸めることで、KPOINTSファイル内の表記をより簡潔かつ正確にします。

  5. VASP KPOINTSファイルの出力: 決定された高対称性経路とK点分割数に基づき、VASPのラインモード形式でKPOINTSファイルを生成し、指定されたファイル名で保存します。

解決する課題

  • 手動でのKPOINTSファイル作成における労力と誤りのリスクの軽減。

  • 複雑な結晶構造における高対称性K点経路の正確な同定の自動化。

  • 異なる高対称性パス慣例への対応。

原理

make_kpoints.py は、主にpymatgenライブラリの結晶学および対称性解析機能を利用してKPOINTSファイルを生成します。

結晶学と対称性解析

プログラムは、pymatgen.io.cif.CifParser を用いて入力CIFファイルから結晶構造を読み込みます。読み込まれた構造は pymatgen.symmetry.analyzer.SpacegroupAnalyzer に渡され、以下の処理が行われます。

  • 空間群の決定: 結晶の空間群が自動的に解析されます。

  • プリミティブセルへの変換: オプションで、CIFファイルから読み込んだ構造を標準的なプリミティブセルに変換します。この変換は、symprec (位置の許容誤差) および angle_tolerance (角度の許容誤差) パラメータに基づいて行われ、結晶サイトの対称性を判断します。

高対称性K点経路の決定

プリミティブセルまたは指定された構造に基づいて、pymatgen.symmetry.bandstructure.HighSymmKpath クラスがインスタンス化されます。このクラスは、結晶のブラベー格子タイプと空間群情報に基づき、第一ブリルアンゾーン内の高対称点とその経路を自動的に決定します。 高対称性経路の決定には、以下の慣例が選択可能です。

  • setyawan_curtarolo: Setyawan & Curtarolo (2010) に基づくパス。

  • latimer_munro: Latimer & Munro (2015) に基づくパス。

  • hinuma: Hinuma et al. (2017) に基づくパス。 これらの経路は、通常、ブリルアンゾーンの特定の高対称点（例: \(\Gamma\), X, L, Kなど）を結び、バンド構造計算で重要な電子状態の変化を捉えるために使用されます。

K点座標の丸め

snap 関数は、pymatgen から取得された浮動小数点数のK点座標を、より簡潔な分数表現に丸めます。これは、Pythonの fractions.Fraction クラスの limit_denominator() メソッドを利用して行われます。 具体的には、座標 \(c\) は \(Fraction(c).limit_denominator(max\_den)\) によって、指定された最大分母 max_den までの分数に変換されます。 例: \(0.33333333 \rightarrow 1/3\) （max_den を3以上とした場合）

この処理により、生成されるKPOINTSファイル内の座標が、理論的な高対称点座標に正確に一致するようになります。

VASP KPOINTSファイル形式

最終的に、プログラムは pymatgen.io.vasp.inputs.Kpoints.automatic_linemode メソッドを使用してVASPのラインモードKPOINTSファイルを生成します。この形式は、高対称点のペアと各セグメントでのK点分割数を指定することで、ブリルアンゾーン内の特定の経路に沿ってK点をサンプリングするものです。 ファイル構造は以下のようになります。

  1. コメント行

  2. 各セグメントあたりのK点分割数

  3. Line-mode

  4. Reciprocal (または Cartesian, Direct。本プログラムではReciprocalを使用)

  5. 高対称点セグメントの定義（始点と終点のラベル、分数座標）

\[\begin{split} \text{LABEL}_1 \quad k_{x1} \quad k_{y1} \quad k_{z1} \\ \text{LABEL}_2 \quad k_{x2} \quad k_{y2} \quad k_{z2} \\ \quad \\ \text{LABEL}_2 \quad k_{x2} \quad k_{y2} \quad k_{z2} \\ \text{LABEL}_3 \quad k_{x3} \quad k_{y3} \quad k_{z3} \\ \quad \\ \dots \end{split}\]

必要な非標準ライブラリとインストール方法

make_kpoints.py は、以下の非標準Pythonライブラリを使用します。

  • pymatgen: 材料科学計算のための強力なオープンソースライブラリ。結晶構造の読み込み、対称性解析、K点パスの生成など、このプログラムの主要な機能を提供します。

インストール方法

pip コマンドを使用してインストールできます。

pip install pymatgen

必要な入力ファイル

プログラムは、Crystallographic Information File (CIF) 形式 の入力ファイルを1つ必要とします。

  • ファイル形式: .cif 拡張子を持つ標準的なCIFファイル。

  • ファイル名: コマンドライン引数で指定します。

  • 内容: 結晶構造に関する情報が含まれている必要があります。具体的には、以下の情報が期待されます。

    • 格子定数 (a, b, c) および格子角 (\(\alpha\), \(\beta\), \(\gamma\))

    • 原子の化学種と分数座標 (x, y, z)

    • 空間群の情報（存在すれば、解析精度が向上します）

例: POSCAR.cif, mp-149.cif など。

生成される出力ファイル

プログラムは、VASPがバンド構造計算に利用する KPOINTSファイル を生成します。

  • ファイル名:

    • デフォルト: KPOINTS

    • -o または --output オプションで変更可能 (例: KPOINTS.band)

  • 内容: VASPのラインモードKPOINTSファイルです。このファイルには、コメント行、各K点パスセグメントの分割数、およびブリルアンゾーン内の高対称点間の経路を定義するK点座標とそのラベルが含まれます。K点座標は逆格子空間での分数座標として記述されます。

出力ファイルの内容の例:

Generated by pymatgen.io.vasp.inputs.Kpoints
20
Line-mode
Reciprocal
  Gamma        0.00000000   0.00000000   0.00000000
  X            0.50000000   0.00000000   0.50000000

  X            0.50000000   0.00000000   0.50000000
  M            0.50000000   0.50000000   0.00000000

  M            0.50000000   0.50000000   0.00000000
  R            0.50000000   0.50000000   0.50000000

  R            0.50000000   0.50000000   0.50000000
  Gamma        0.00000000   0.00000000   0.00000000

上記の例では、GammaからX、XからM、MからR、RからGammaへと続く経路に沿って、各セグメントが20分割されたK点が定義されています。

コマンドラインでの使用例 (Usage)

make_kpoints.py は、以下の一般的な形式でコマンドラインから実行されます。

python make_kpoints.py <ciffile> [options]

  • <ciffile>: 必須。入力CIFファイルへのパスを指定します。

主要なオプション

  • --primitive_on_read: CIFファイルを読み込む際に、pymatgen によってプリミティブセルに変換します。

  • -c, --conventional: CIFから読み込んだ構造をそのまま使用し、プリミティブセルへの標準化・変換を行いません。

  • -d, --max_den <int>: 逆格子空間の分数座標を丸める際の分母の最大値。デフォルトは4。

  • -n, --ndivisions <int>: 各K点パスセグメントに沿って生成するK点の分割数。デフォルトは20。

  • -p, --path-type <type>: 高対称性パスの慣例を指定します。選択肢は setyawan_curtarolo (デフォルト), latimer_munro, hinuma, all。

  • -o, --output <filename>: 生成されるKPOINTSファイルの出力ファイル名。デフォルトは KPOINTS。

  • -s, --symprec <float>: 対称性検出のための位置許容誤差。デフォルトは1e-4。

  • -a, --angle-tol <float>: 対称性検出のための角度許容誤差（度）。デフォルトは0.1。

  • -f, --frac_tolerance <float>: 構造パラメータの分数許容誤差。デフォルトは1e-4。

  • --atol <float>: ブリルアンゾーン上の点や線の対称性等価性を決定するための絶対許容誤差。デフォルトは0.1。

  • --international-monoclinic: 単斜晶系の標準化において、国際慣例を使用します。

  • --keep-site-properties: プリミティブ標準構造に削減する際に、元のサイトプロパティを保持します。

コマンドラインでの具体的な使用例

ここでは、架空のCIFファイル mp-149.cif (例として、酸化マグネシウムMgOの構造を想定) を使用した具体的な実行例を示します。

  1. 基本的な使用例: mp-149.cif からKPOINTSファイルを生成します。デフォルト設定（Setyawan-Curtarolo経路、各セグメント20分割、K点座標の分母の最大値4、出力ファイル名 KPOINTS）が適用され、構造はプリミティブセルに変換されます。

    python make_kpoints.py mp-149.cif

    実行結果の説明: 標準出力には、読み込まれた引数、CIFファイルの解析結果（構造情報、空間群）、プリミティブセルへの変換情報、生成された高対称K点経路とその座標（丸め処理後）、そして最終的なKPOINTSファイルの内容が表示されます。最後に「Wrote KPOINTS to 'KPOINTS'」というメッセージで出力完了が通知されます。

  2. 出力ファイル名を指定し、K点分割数を変更する例: 出力ファイルを KPOINTS_band.vasp とし、各パスセグメントのK点分割数を30に変更してKPOINTSファイルを生成します。

    python make_kpoints.py mp-149.cif -o KPOINTS_band.vasp -n 30

    実行結果の説明: 上記の基本例と同様の情報が出力されますが、特に Arguments セクションでは output: KPOINTS_band.vasp と ndivisions: 30 が表示されます。最終的に生成されるKPOINTSファイルの内容の2行目が 30 となり、ファイル名が KPOINTS_band.vasp に変更されます。

  3. 分母の丸め精度とパスタイプを指定する例: K点座標の分数表記の分母の最大値を2に制限し、高対称性パスの慣例として hinuma を採用します。

    python make_kpoints.py mp-149.cif -d 2 -p hinuma

    実行結果の説明: 出力される Arguments には max_den: 2 と path_type: hinuma が示されます。高対称点座標の表示では、例えば [0.5, 0.5, 0.0] のような座標はそのままですが、[0.33333, 0.33333, 0.33333] のような座標は [0.5, 0.5, 0.5] (max_den=2で最も近い分数) に丸められる可能性があり、High-symmetry k-points の表示でその効果が確認できます。kpath のセグメントも hinuma の慣例に従ったものになります。

  4. プリミティブセルへの変換を抑制し、従来セルを維持する例: CIFファイルに記述されているそのままのセル（従来セル）を使用してK点パスを生成します。

    python make_kpoints.py mp-149.cif --conventional

    実行結果の説明: Arguments セクションで conventional: True と表示されます。また、Read CIF file and generate KPOINTS for VASP の後のメッセージで Use conventional cell: True となり、Standardize and reduce to primitive cell のプロセスがスキップされたことを示す情報が出力されます。これにより、K点経路は元の従来セルに基づき決定されます。

これらの実行例では、make_kpoints.py が標準出力に詳細なログを出力するため、各オプションの動作と結果を容易に確認できます。最終的に生成された KPOINTS ファイルは、VASP計算の準備が整います。