.. _sec-getcif-tutorial: チュートリアル ================================================================ 結晶構造などのデータを物質材料データベースから取得するツール 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 にセットするには、以下のいずれかを実行します。 (a) pymatgen の設定ファイルに登録する .. code:: bash $ pmg config --add PMG_MAPI_KEY を実行するか、設定ファイル ``~/.config/.pmgrc`` に .. code:: bash PMG_MAPI_KEY: を書き込みます。 (b) 環境変数にセットする .. code:: bash $ MP_API_KEY="" $ export MP_API_KEY を実行します。 (c) ファイルに格納する APIキーをファイルに書き込み、getcif を実行するディレクトリに配置します。ファイル名のデフォルトは ``materials_project.key`` です。異なるファイル名を使う場合は、入力パラメータファイル (input.yaml) の api_key_file にファイル名を指定します。ファイル名は ``.key`` の拡張子が必要です。 .. code:: yaml database: api_key_file: materials_project.key 註: バージョン管理ツールを使っている場合は、 ``.key`` の拡張子を持つファイルを管理から除外するとよいでしょう。(Git の場合は ``.gitignore`` ファイルに ``*.key`` を追加します。) 入力パラメータファイルを作成する ---------------------------------------------------------------- 入力パラメータファイルにはデータベース検索および出力についての設定を記述します。 以下に入力パラメータファイルのサンプルを記載します。このファイルは YAML形式のテキストファイルで、データベースへの接続に必要な情報や、検索条件、取得するデータの種類などの内容を記述します。仕様の詳細については :ref:`ファイルフォーマット ` の章を参照してください。 YAMLフォーマットでは、 ``keyword: value`` の辞書形式でパラメータを記述します。 ``value`` には数値や文字列などのスカラー値や、複数の値を ``[ ]`` または箇条書きの形式で列挙するリスト型、または辞書型を入れ子にすることができます。検索条件と出力項目については、特別な記法として、リスト型を括弧を使わず空白区切りで列挙する形式でも書くことができます。 .. literalinclude:: ../../../../tutorial/getcif/input.yaml :language: yaml 入力パラメータファイルは ``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 を実行します。 .. code-block:: bash $ getcif input.yaml ``getcif`` を実行すると Materials Project のデータベースに接続し、検索条件に合致するデータを取得します。標準出力には、以下のように、物質の material ID と組成式、データ項目のサマリーが出力されます。 .. literalinclude:: ../../../../tutorial/getcif/output_log.txt :language: text 取得したデータは、 ``output_dir`` で指定した result ディレクトリ内に物質ごとに格納されます。この例では、 result 以下に mp-3163 から mp-977455 までの 7つのディレクトリが作成され、各ディレクトリには次のファイルが書き込まれます。 - band_gap バンドギャップの値 - formula 組成式 (formula_pretty に対応します) - structure.cif CIF形式の結晶構造データ - symmetry 対称性に関するデータ ``getcif`` の実行に ``--dry-run`` オプションを付けると、以下のように検索条件を出力して終了します。データベースに実際に接続する前に検索項目を確認できます。 .. literalinclude:: ../../../../tutorial/getcif/output_dryrun.txt :language: text