get_cif.py Technical Document

プログラムの動作

get_cif.py は、Materials Project のAPIを利用して、指定された化学式または構成元素リストに対応する結晶構造データ（CIF形式）を取得し、ローカルファイルとして保存するためのPythonスクリプトです。

主な機能:

  • コマンドライン引数として化学式（例: Fe2O3）または構成元素のカンマ区切りリスト（例: Fe,O）を受け取ります。

  • Materials ProjectのAPIキー（環境変数 MP_APIKEY から取得）を使用して、Materials Projectデータベースにアクセスします。

  • 指定された条件に合致する結晶構造データをMaterials Projectから検索し、取得します。

  • 取得した構造データは pymatgen ライブラリの Structure オブジェクトに変換され、さらに SpacegroupAnalyzer によって対称化処理が施されます。対称性の判定には、ユーザーが指定可能な許容誤差（prec）が使用されます。

  • 対称化された構造は、CIF (Crystallographic Information File) 形式のファイルとしてローカルに保存されます。

解決する課題:

材料科学研究者がMaterials Projectの豊富な結晶構造データベースから特定の物質のデータを容易に検索・取得し、計算化学ソフトウェアなどで利用可能な標準的なファイル形式（CIF）として手元に保存する手間を軽減します。これにより、手動でのデータダウンロードやフォーマット変換の必要がなくなります。

原理

get_cif.py は主に mp_api および pymatgen という二つの強力なPythonライブラリを活用して動作します。

Materials Project API と mp_api

  • Materials Project (MP): 世界最大級のオープンな材料科学データベースであり、数万種類以上の無機結晶に関する計算された特性データを提供しています。

  • mp_api.client.MPRester: このライブラリは、PythonからMaterials ProjectのRESTful APIにアクセスするためのインターフェースを提供します。ユーザーはAPIキーを介して認証を行い、データベースに対して検索クエリを発行し、材料のサマリー情報、詳細な構造データ、電子特性、熱力学的安定性などの情報をプログラム的に取得できます。

  • 検索アルゴリズム:

    1. スクリプトは、入力された化学式にカンマ , が含まれるかどうかで検索方法を分岐します。

    2. もしカンマが含まれる場合（例: Fe,O）、これは構成元素のリストとして解釈され、これらの元素を全て含む化合物が検索されます。

    3. カンマが含まれない場合（例: Fe2O3）、これは具体的な化学式として解釈され、その化学式に一致する化合物が検索されます。

    4. 検索結果は search_results として取得され、各結果の material_id を用いて、個々の材料の詳細な構造データがさらに取得されます。

Pymatgen ライブラリ

  • pymatgen.core.structure.Structure: 結晶構造を表現するための中心的なオブジェクトです。このオブジェクトは、格子の幾何学的情報（格子ベクトル、格子定数、角度）、構成原子の種類とその分数座標、および組成などの情報を含みます。Materials Projectから取得した辞書形式の構造データは、この Structure オブジェクトに変換されて処理されます。

  • pymatgen.symmetry.analyzer.SpacegroupAnalyzer: 結晶構造の対称性を解析し、構造を対称化するためのクラスです。

    • symprec (Symmetry Precision): 対称操作を判定する際の許容誤差（単位: オングストローム）。原子位置や格子定数の微小なずれを許容して対称性を識別するために使用されます。例えば、わずかに歪んだ構造も理想的な対称構造として扱われるように調整できます。このパラメータは、距離の許容誤差 \(d_{tol}\) に対応します。

    • symmetrized_structure: SpacegroupAnalyzer は、構造の対称要素（空間群、点群など）を特定し、その情報に基づいて構造を理想的な対称位置に「調整」します。これにより、計算結果の一貫性が向上し、標準的な結晶構造データベース（例: ICSD）との比較が容易になります。

  • pymatgen.io.cif.CifWriter: Structure オブジェクトを標準的なCIF形式でファイルに書き出すためのクラスです。CIFは結晶学で広く用いられるテキストベースのデータ交換形式であり、格子、原子位置、空間群、温度因子などの情報を含みます。

アルゴリズムの概要

  1. 初期化: コマンドライン引数を解析し、対象化学式 (formula)、出力形式 (output_format)、対称性許容誤差 (prec) を設定します。

  2. APIキー取得: 環境変数 MP_APIKEY からMaterials ProjectのAPIキーを取得し、MPRester オブジェクトを初期化します。

  3. 構造検索: formula に基づいてMaterials Projectから構造を検索します。

    • カンマ区切りの元素リストの場合は、その元素を含む化合物を検索。

    • 単一の化学式の場合は、その化学式に厳密に一致する化合物を検索。

  4. 構造データの処理: 検索された各材料について、以下の処理を行います。

    • Materials Projectから詳細な構造データを取得します。

    • データを pymatgen.core.structure.Structure オブジェクトに変換します。

    • もし入力が元素リストであった場合、取得した構造が指定された元素のみで構成されているかを確認します。

    • 条件を満たすすべての構造をリストに集めます。

  5. 構造の保存: 収集された各構造について、以下の処理を行います。

    • SpacegroupAnalyzer を使用し、指定された prec 値で構造を対称化します。

    • CifWriter を使用して、対称化された構造を {reduced_formula}_{material_id}.cif という命名規則のファイルにCIF形式で保存します。

    • なお、output_format が "poscar" と指定されても、現在の実装ではファイル拡張子のみが .poscar となり、ファイル内容はCIF形式で書き出されます。

対称性許容誤差 prec は、原子が理想的な対称位置からどれだけ離れていても同じ対称性を共有すると見なすかを定義する物理的な距離です。この値は SpacegroupAnalyzer の symprec パラメータとして渡され、以下のように対応します。 $\(d_{tol} = prec\)\( ここで \)d_{tol}$ は検出されるべき対称要素間の最大距離であり、prec はユーザーが指定する許容誤差です。

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

このプログラムの実行には、以下の非標準Pythonライブラリが必要です。

  • mp_api: Materials Project REST APIへのアクセス用

  • pymatgen: 結晶構造の処理、対称性解析、およびCIFファイルの書き出し用

これらのライブラリは、Pythonのパッケージマネージャ pip を使用してインストールできます。

pip install mp-api pymatgen

必要な入力ファイル

get_cif.py は、外部の入力ファイルを直接読み込むことはありません。必要な情報はコマンドライン引数と環境変数を通じて提供されます。

  • コマンドライン引数:

    • formula: 必須。取得したい結晶構造の化学式（例: Fe2O3）または構成元素のカンマ区切りリスト（例: Fe,O）。

    • output_format: オプション。出力ファイルの形式を指定しますが、現在の実装ではファイル名の拡張子にのみ影響し、出力内容は常にCIF形式です。デフォルトは cif。

    • prec: オプション。対称性解析の許容誤差（浮動小数点数）。デフォルトは 1.0e-3 オングストローム。

  • 環境変数:

    • MP_APIKEY: Materials ProjectのAPIキーを設定する必要があります。Materials Projectのウェブサイトでユーザー登録後、アカウントページからAPIキーを取得できます。

      • Linux/macOSの場合:

        export MP_APIKEY="YOUR_API_KEY_HERE"

      • Windows (CMD) の場合:

        set MP_APIKEY="YOUR_API_KEY_HERE"

      • Windows (PowerShell) の場合:

        $env:MP_APIKEY="YOUR_API_KEY_HERE"

      YOUR_API_KEY_HERE は取得した実際のAPIキーに置き換えてください。

生成される出力ファイル

プログラムは、Materials Projectから取得・処理された各結晶構造に対して1つのCIFファイルを生成します。

  • ファイル名:

    • {reduced_formula}_{material_id}.cif の形式でファイルが保存されます。

      • reduced_formula: 構造の組成を最小の整数比で表した化学式（例: Fe2O3）。

      • material_id: Materials Projectが各材料に割り当てるユニークなID（例: mp-1913）。

    • 特別なケース: コマンドライン引数で output_format が "poscar" と指定された場合、ファイル名は POSCAR または POSCAR_2 (2番目以降の構造の場合) のようになりますが、ファイルの内容は常にCIF形式です。これはプログラムの現在の実装によるものです。

  • ファイル内容:

    • 標準的なCIF (Crystallographic Information File) 形式のテキストデータ。

    • _cell_length_a, _cell_length_b, _cell_length_c (格子定数)

    • _cell_angle_alpha, _cell_angle_beta, _cell_angle_gamma (格子角)

    • _symmetry_space_group_name_H-M (ヘルマン・モーガン記号による空間群名)

    • _symmetry_Int_Tables_number (国際結晶学便覧番号)

    • _atom_site_label, _atom_site_type_symbol, _atom_site_fract_x, _atom_site_fract_y, _atom_site_fract_z (原子のサイトラベル、元素記号、分数座標)

    • Materials Projectに関連する追加情報 (_exptl_absorpt_coefficient, _computing_code, _computing_data_collection など)

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

プログラムの基本的な実行コマンドと引数の説明は以下の通りです。

python get_cif.py formula [output_format] [prec]

  • formula:

    • 必須引数。取得したい化学式（例: TiO2）または構成元素のカンマ区切りリスト（例: Ti,O）を指定します。

  • output_format:

    • オプション引数。出力ファイルの形式を指定します。現在、この引数は出力ファイルの拡張子のみに影響し、内容は常にCIF形式です。デフォルト値は cif です。

  • prec:

    • オプション引数。結晶構造の対称性解析における許容誤差を浮動小数点数で指定します。単位はオングストローム (\(Å\)) です。この値が大きいほど、多少の歪みがあってもより高い対称性を持つと判断されやすくなります。デフォルト値は \(1.0 \times 10^{-3}\) です。

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

例1: 基本的な使用例（二酸化チタンのCIFを取得）

コマンド:

python get_cif.py TiO2

実行結果の説明: Materials Projectデータベースから二酸化チタン (TiO2) の結晶構造を検索します。検索結果が1つ以上見つかった場合、それぞれの構造は TiO2_{material_id}.cif の形式でファイルに保存されます。例えば、以下のような出力が得られ、TiO2_mp-2657.cif と TiO2_mp-390.cif というファイルが生成される可能性があります（Materials Projectのデータベース更新により material_id は変化する可能性があります）。

Found material_id for TiO2: mp-2657: TiO2
Found material_id for TiO2: mp-390: TiO2

Saving TiO2 structure to [TiO2_mp-2657.cif]...
Saving TiO2 structure to [TiO2_mp-390.cif]...

Usage: python get_cif.py formula [output_format] [prec]

Press ENTER to terminate>>

例2: 複数元素を含む化合物の取得（鉄と酸素を含むすべての化合物のCIFを取得）

コマンド:

python get_cif.py Fe,O

実行結果の説明: Materials Projectデータベースから鉄 (Fe) と酸素 (O) の両方を含むすべての安定な化合物を検索します。これにより、例えば酸化鉄(II) (FeO)、酸化鉄(III) (Fe2O3)、四酸化三鉄 (Fe3O4) など、複数の構造が見つかる可能性があります。それぞれの構造は FeO_{material_id}.cif、Fe2O3_{material_id}.cif のように、異なるファイル名で保存されます。

  ** Found [Fe2O3] [mp-1913]
Found material_id for Fe,O: mp-1913: Fe2O3
  ** Found [FeO] [mp-1959]
Found material_id for Fe,O: mp-1959: FeO
  ** Found [Fe3O4] [mp-1869]
Found material_id for Fe,O: mp-1869: Fe3O4

Saving Fe2O3 structure to [Fe2O3_mp-1913.cif]...
Saving FeO structure to [FeO_mp-1959.cif]...
Saving Fe3O4 structure to [Fe3O4_mp-1869.cif]...

Usage: python get_cif.py formula [output_format] [prec]

Press ENTER to terminate>>

例3: 出力ファイル名と対称性許容誤差の指定

コマンド:

python get_cif.py ZnO poscar 0.01

実行結果の説明: 酸化亜鉛 (ZnO) の結晶構造を検索します。出力形式として poscar が指定されているため、ファイル名は ZnO_mp-XXXX.poscar のようになります。しかし、繰り返しますが、ファイルの内容はCIF形式です。対称性解析の許容誤差 prec は \(0.01\) オングストロームに設定されます。これにより、デフォルト値 \(0.001\) オングストロームよりも緩やかな対称性判定が行われます。

Found material_id for ZnO: mp-2133: ZnO

Saving ZnO structure to [ZnO_mp-2133.poscar]...

Usage: python get_cif.py formula [output_format] [prec]

Press ENTER to terminate>>