7.2. チュートリアル

結晶構造などのデータを物質材料データベースから取得するツール getcif を使うには、検索条件と取得するデータを記述した入力パラメータファイルを作成し、プログラム getcif を実行します。現在は Materials Project が公開しているデータベースに対応しています。以下では docs/tutorial/getcif ディレクトリにある ABO3 系の物質を検索・取得するサンプルを例にチュートリアルを実施します。

APIキーを取得する

Materials Project のデータベースをプログラムから検索するには、あらかじめ Materials Project にユーザ登録し、APIキーを取得する必要があります。 Materials Project の公式サイト https://next-gen.materialsproject.org にアクセスし、Login します。APIキーはユーザ登録時に自動的生成され、ユーザのダッシュボードから確認できます。取得した APIキーは安全に保管し、他人に知られないようにしましょう。

APIキーを getcif にセットするには、以下のいずれかを実行します。

1. pymatgen の設定ファイルに登録する

   $ pmg config --add PMG_MAPI_KEY <API_KEY>
   

   を実行するか、設定ファイル ~/.config/.pmgrc に

   PMG_MAPI_KEY: <API_KEY>
   

   を書き込みます。

2. 環境変数にセットする

   $ MP_API_KEY="<API_KEY>"
   $ export MP_API_KEY
   

   を実行します。

3. ファイルに格納する

   APIキーをファイルに書き込み、getcif を実行するディレクトリに配置します。ファイル名のデフォルトは materials_project.key です。異なるファイル名を使う場合は、入力パラメータファイル (input.yaml) の api_key_file にファイル名を指定します。ファイル名は .key の拡張子が必要です。

   database:
     api_key_file: materials_project.key
   

   註: バージョン管理ツールを使っている場合は、 .key の拡張子を持つファイルを管理から除外するとよいでしょう。(Git の場合は .gitignore ファイルに *.key を追加します。)

入力パラメータファイルを作成する

入力パラメータファイルにはデータベース検索および出力についての設定を記述します。

以下に入力パラメータファイルのサンプルを記載します。このファイルは YAML形式のテキストファイルで、データベースへの接続に必要な情報や、検索条件、取得するデータの種類などの内容を記述します。仕様の詳細については ファイルフォーマット の章を参照してください。

YAMLフォーマットでは、 keyword: value の辞書形式でパラメータを記述します。 value には数値や文字列などのスカラー値や、複数の値を [ ] または箇条書きの形式で列挙するリスト型、または辞書型を入れ子にすることができます。検索条件と出力項目については、特別な記法として、リスト型を括弧を使わず空白区切りで列挙する形式でも書くことができます。

database:
  target: materials project

option:
  output_dir: result
  # dry_run: false

properties:
  band_gap: < 1.0
  is_stable: true
  is_metal: false
  formula: "**O3"
  spacegroup_symbol: Pm-3m

fields: |
  structure
  band_gap
  symmetry

入力パラメータファイルは database, option, properties, fields のブロックからなります。 database にはデータベース接続に関する設定を記述します。例では target に Materials Project を指定していますが、現時点ではこの項目は無視されます。その他、 api_key に APIキーを指定できます。APIキーは pymatgen の設定ファイルや環境変数にセットすることもできます。例では後者の方式を仮定しています。

option には実行時のオプションを記述します。 output_dir は取得したデータの格納先ディレクトリを指定します。省略時にはカレントディレクトリに書き出されます。 dry_run を true にセットすると、データベースへの接続はせず、検索条件を出力して終了します。 dry_run はコマンドラインオプションでも指定できます。

properties は検索条件の指定を行います。検索条件を「項目: 値」の書式で列挙し、これらの条件は AND で扱われます。例では、バンドギャップが 1.0以下、安定な絶縁体で、組成式は ABO3 (A, B は任意の元素種)、空間群は Pm-3m という条件を指定しています。 band_gap には値の範囲を上限・下限の組で指定するほか、 < 1.0 のような記法も使用できます。検索条件にどのような項目が指定できるかは Appendix を参照してください。

fields には出力項目を列挙します。YAMLのリスト形式のほか、空白区切りで項目を列挙する書き方もできます。また、例に示したとおり、YAMLの記法を使って複数行で書くこともできます。 structure は結晶構造データで、取得したデータはCIF形式で出力されます。 band_gap はバンドギャップの数値、 symmetry は対称性の情報です。この他に、 material_id で Materials Project 内の物質データのインデックスと、 formula_pretty で組成式が暗黙的に取得されます。出力項目の一覧は Appendix を参照してください。また、getcif コマンドのヘルプメッセージにも一覧が出力されます。

データを取得する

入力パラメータファイル(input.yaml)を引数として getcif を実行します。

$ getcif input.yaml

getcif を実行すると Materials Project のデータベースに接続し、検索条件に合致するデータを取得します。標準出力には、以下のように、物質の material ID と組成式、データ項目のサマリーが出力されます。

material_id  formula  band_gap  symmetry  formula_pretty
mp-861502  AcFeO3  0.9887999999999995  crystal_system=<CrystalSystem.cubic: 'Cubic'> symbol='Pm-3m' number=221 point_group='m-3m' symprec=0.1 version='2.0.2'  AcFeO3
mp-977455  PaAgO3  0.915  crystal_system=<CrystalSystem.cubic: 'Cubic'> symbol='Pm-3m' number=221 point_group='m-3m' symprec=0.1 version='2.0.2'  PaAgO3
mp-11775  RbUO3  0.45420000000000016  crystal_system=<CrystalSystem.cubic: 'Cubic'> symbol='Pm-3m' number=221 point_group='m-3m' symprec=0.1 version='2.0.2'  RbUO3
mp-3163  BaSnO3  0.37239999999999984  crystal_system=<CrystalSystem.cubic: 'Cubic'> symbol='Pm-3m' number=221 point_group='m-3m' symprec=0.1 version='2.0.2'  BaSnO3
mp-4126  KUO3  0.44540000000000024  crystal_system=<CrystalSystem.cubic: 'Cubic'> symbol='Pm-3m' number=221 point_group='m-3m' symprec=0.1 version='2.0.2'  KUO3
mp-865322  UTlO3  0.27360000000000007  crystal_system=<CrystalSystem.cubic: 'Cubic'> symbol='Pm-3m' number=221 point_group='m-3m' symprec=0.1 version='2.0.2'  UTlO3
mp-753781  EuHfO3  0.4795999999999996  crystal_system=<CrystalSystem.cubic: 'Cubic'> symbol='Pm-3m' number=221 point_group='m-3m' symprec=0.1 version='2.0.2'  EuHfO3

取得したデータは、 output_dir で指定した result ディレクトリ内に物質ごとに格納されます。この例では、 result 以下に mp-3163 から mp-977455 までの 7つのディレクトリが作成され、各ディレクトリには次のファイルが書き込まれます。

• band_gap

  バンドギャップの値

• formula

  組成式 (formula_pretty に対応します)

• structure.cif

  CIF形式の結晶構造データ

• symmetry

  対称性に関するデータ

getcif の実行に --dry-run オプションを付けると、以下のように検索条件を出力して終了します。データベースに実際に接続する前に検索項目を確認できます。

$ getcif --dry-run input.yaml
{'band_gap': (None, 1.0), 'is_stable': True, 'is_metal': False, 'formula': '**O3', 'spacegroup_symbol': 'Pm-3m', 'fields': ['structure', 'band_gap', 'symmetry', 'material_id', 'formula_pretty']}