【入門】pymatgen インストール、環境構築からデータ取得までやってみる

# はじめに
この記事では、pymatgenを用いてMaterials Projectからデータを取得する方法を解説します。具体的には以下の内容を扱います。
- pymatgenのインストール、環境構築
- Materials Project APIキーの取得
- pymatgenでMaterials Projectに接続
- 材料データを取得

※基本的にはWindowsを前提とします。

## この記事の対象者
- 材料科学やマテリアルズインフォマティクスに興味がある
- pymategenやMaterials Projectを利用してみたいが、よくわからない
- Pythonのインストールはできている

## pymatgenとは？
pymatgenは、材料科学の研究者が日々の研究活動で必要とする様々なツールを提供する、強力なPythonライブラリです。**結晶構造の解析、物性値の計算、シミュレーションの実行など、材料科学に関する様々なタスクをPython上で実行できます**。

## Materials Projectとは？
Materials Projectは、**マテリアルズインフォマティクス（MI）の推進を目的とした世界最大級のオープンアクセスな材料データベース**です。アメリカのローレンス・バークレー国立研究所が中心となって運営されており、世界中の研究者がデータを利用・共有できるプラットフォームを提供しています。第一原理計算によって得られた、様々な材料の結晶構造や物性値などのデータが公開されています。

# 1. pymatgenのインストール
pymatgenのインストール方法には、pipとcondaの2つの方法があります。1.1か1.2のどちらかでインストールを行ってみてください。筆者はconda環境を使ってインストールを行いました。2025年2月現在、[公式サイト](https://pymatgen.org/)の記載によると>=3.10のPythonに対応しているとことなので、Python3.12を使っていきます。ただ、適宜ほかのバージョンを使っていただいても大丈夫だと思われます。
> As of 2024, pymatgen supports Python 3.10 and above. 

## 1.1 pipを使ったインストール
pipは、Pythonのパッケージ管理システムで、pymatgenを簡単にインストールできます。ターミナルまたはコマンドプロンプトで以下のコマンドを実行してください。
```:ターミナルまたはコマンドプロンプト
pip install pymatgen
```

## 1.2 condaを使ったインストール
anacondaでもpipと同様にpymatgenをインストールできます。anacondaを使う場合は、まずconda環境を作成しその中でpymatgenをインストールすることを推奨します。anacondaのインストール方法はほかにたくさんの方が解説してくださっているので、ここでは割愛します。

1\. conda環境を作成
```:ターミナルまたはコマンドプロンプト
conda create -n pymatgen python=3.12
```
ここでは"pymatgen"という仮想環境を作成しています。pythonのバージョンは今回は3.12を選んでいますが、適宜指定してください。

:::note warn
ここでエラーが出る場合は環境変数が通っていない可能性が高いです。その場合は検索バーから「Anaconda Prompt」を検索して起動してください。(anacondaのインストール時に一緒に入っているはずです)
:::



2\. 仮想環境をアクティベートする
```:ターミナルまたはコマンドプロンプト
conda activate pymatgen
```

3\. pymatgenをインストール
```:ターミナルまたはコマンドプロンプト
conda install -c conda-forge pymatgen
```

## 1.3 インストール確認
インストールが完了したら、Pythonインタプリタでpymatgenをインポートできることを確認します。
```:ターミナルまたはコマンドプロンプト
python
```
と入力するとPythonインタプリタに入りますので、以下のように入力します。

```python:Python
import pymatgen
```
ここでエラーが出なければインストールは正常に完了しています。
念のため、インストールされたpymatgenのバージョンを確認してみます。
以下のコマンドにより、現在の仮想環境にインストールされたライブラリの一覧が表示されます。
```:ターミナルまたはコマンドプロンプト
conda list
```
スクロールしてpymatgenの行を確認すると、以下のように表示されました。2024.10.3というバージョンがインストールされたようですね。
```:出力結果
pymatgen                  2024.10.3       py313h8e081ca_1    conda-forge
```

# 2. Materials Project APIキーの取得
Materials Projectのデータにpymatgenからアクセスするには、APIキーが必要です。APIキーは、Materials Projectのウェブサイトで取得できます。

## 2.1 Materials Projectアカウントの作成
[Materials Projectのウェブサイト](https://next-gen.materialsproject.org/) にアクセスし、アカウントを作成してください。右上の"login"ボタンをクリックするとアカウント作成画面に飛ぶはずです。

## 2.2 APIキーの取得
1. Materials Projectにログイン後、ウェブサイトの右上にある人型アイコンをクリックし、「Dashboard」を選択してください。
2. DashboardページにAPI Keysという項目があります。
3. APIキーが表示されていない場合は、「Generate API Key」ボタンをクリックしてください。APIキーが生成されます。
4. 表示されたAPIキーをコピーしてください。

:::note warn
取得したAPIキーはMaterials Projectへのアクセス認証に使用されるため、他人に知られないようにしましょう。APIキーを紛失した場合は、Materials Projectのウェブサイトで再生成できます。
:::

# 3. pymatgenでMaterials Projectに接続
pymatgenを使ってMaterials Projectに接続するには、MPResterクラスを使用します。MPResterクラスは、Materials ProjectのAPIにアクセスするためのインターフェースとなるクラスです。MPResterクラスを使ってデータを取得するコードを書いていきます。好きなディレクトリに.pyファイルを作成し、その中に書いてみてください。

## 3.1 MPResterのインポート
まず、pymatgen.ext.matprojモジュールからMPResterクラスをインポートします。
```python:Python
from pymatgen.ext.matproj import MPRester
```

## 3.2 APIキーの設定
Materials ProjectのAPIキーをMPResterクラスの引数として渡します。
```python:Python
API_KEY = "YOUR_API_KEY" # 2.2で取得したAPIキーを入力
```

## 3.3 MPResterのインスタンス化
MPResterクラスのインスタンスを作成することで、Materials Projectへの接続が確立されます。
```python:Python
with MPRester(API_KEY) as m:
    # Materials Projectへの接続が確立
    pass
```

## 3.4 接続確認
MPResterのインスタンスが正常に作成されれば、Materials Projectへの接続は成功です。接続を確認するために、MPResterのメソッドを試してみましょう。get_material_idsメソッドを使ってFe2O3の組成を持つデータのIDリストを取得してみます。

```python:Python
with MPRester(API_KEY) as m:
    material_ids = m.get_material_ids("Fe2O3") # Fe2O3の組成を持つデータのIDリスト
    print(material_ids)
```

ここで以下のようにIDのリストが出力されていればOKです。

```:出力結果
['mp-1244869', 'mp-1244911', 'mp-1245019', 'mp-1245078', 'mp-1245084', 'mp-1245154', 'mp-1245277', 'mp-685153', 'mp-776606', 'mp-557546', 'mp-716814', 'mp-1181824', 'mp-19770', 'mp-565814', 'mp-1068212', 'mp-1356129', 'mp-542896', 'mp-715276', 'mp-715572', 'mp-510080', 'mp-1178392', 'mp-1205415', 'mp-1078361', 'mp-1378486', 'mp-705547', 'mp-1456']
```


# 4. データの取得
Materials Projectへの接続が確立できたら、いよいよデータを取得します。
※3.4で作成したコードを引き続き利用していきますので、以下のコードは3.4のコードに続けて書いてください。

## 4.1 材料情報を取得
Fe2O3の組成を持つ材料のリストを取得できたので、リストの1番目のIDを使って情報を取得してみます。

```python:Python
first_entry = m.get_entry_by_material_id(material_ids[0]) # IDリストの一つ目のIDを使って、データベースの情報を表示
print(first_entry)
```

すると、以下のように様々なデータが表示されているのを確認できます。第一原理計算の計算結果などが記載されているようですね。

```:出力結果
mp-1244911-GGA+U ComputedStructureEntry - Fe32 O48     (Fe2O3)
Energy (Uncorrected)     = -518.0305 eV (-6.4754  eV/atom)
Correction               = -105.1680 eV (-1.3146  eV/atom)
Energy (Final)           = -623.1985 eV (-7.7900  eV/atom)
Energy Adjustments:
  MP2020 anion correction (oxide): -32.9760  eV (-0.4122  eV/atom)
  MP2020 GGA/GGA+U mixing correction (Fe): -72.1920  eV (-0.9024  eV/atom)
Parameters:
  potcar_spec            = [{'titel': 'PAW_PBE Fe_pv 06Sep2000', 'hash': '5963411539032ec3298fa675a32c5e64', 'summary_stats': None}, {'titel': 'PAW_PBE O 08Apr2002', 'hash': '7a25bc5b9a5393f46600a4939d357982', 'summary_stats': None}]
  run_type               = GGA+U
  is_hubbard             = True
  hubbards               = {'Fe': 5.3, 'O': 0.0}
Data:
  oxide_type             = oxide
  aspherical             = True
  last_updated           = 2024-11-21 20:46:03.852017+00:00
  task_id                = mp-1850734
  material_id            = mp-1244911
  oxidation_states       = {'Fe': 3.0, 'O': -2.0}
  license                = BY-C
  run_type               = GGA_U
```

## 4.2 材料の結晶構造を取得
get_structure_by_material_idメソッドを使うと、特定の材料の結晶構造を取得できます。

```python:Python
structure = m.get_structure_by_material_id(material_ids[0])
print(structure)
```
printで見てみると以下のように結晶構造の情報が取得できていることがわかります。

```:出力結果
Full Formula (Fe32 O48)
Reduced Formula: Fe2O3
abc   :  10.651936   9.692614   9.524755
angles:  87.468533  89.303007  89.153745
pbc   :       True       True       True
Sites (80)
  #  SP           a         b         c    magmom
---  ----  --------  --------  --------  --------
  0  Fe    0.6387    0.999961  0.08996      4.325
  1  Fe    0.278182  0.004388  0.606982     4.371
  2  Fe    0.680653  0.820162  0.830422     4.348
  3  Fe    0.820935  0.05931   0.341807     4.318
  4  Fe    0.402211  0.277144  0.218506     4.327
  5  Fe    0.424186  0.344745  0.571023     4.381
  6  Fe    0.444357  0.125108  0.860614     4.343
  7  Fe    0.567255  0.582629  0.057064     4.361
  ～以下略
```

get_structure_by_material_idメソッドは、pymatgenの**Structureオブジェクト**を返します。Structureオブジェクトは、以下の属性を含んでいます。
- lattice: 格子定数と格子角の情報を持つLatticeオブジェクト
- species: 各サイトに存在する原子の種類と占有率の情報を持つSpeciesオブジェクトのリスト
- sites: 各サイトの座標情報を持つSiteオブジェクトのリスト
- composition: 材料の組成情報を表すCompositionオブジェクト
- volume: 単位格子の体積
- density: 材料の密度

例えば、
```python:Python
print(structure.lattice)
```
と入力してlattice属性にアクセスすれば、格子定数や格子角の情報が取得できていることがわかります。
```:出力結果
10.651403 0.069823 0.080490
0.078023 9.689935 0.214114
0.042535 0.210053 9.522344
```

これらの情報に加えて、Structureオブジェクトは様々なメソッドを提供しており、結晶構造の解析や操作に利用できます。
- to(filename, fmt): 構造を様々な形式（CIF, POSCARなど）でファイルに書き出す
- from_file(filename): ファイルから構造を読み込む
- get_neighbors(site, cutoff): 特定のサイトから一定距離内にある原子を検索する
- get_distance(site1, site2): 2つのサイト間の距離を計算する
- add_oxidation_state_by_guess(): 各サイトの酸化数を推定する

こういったメソッドを使いこなすことで、様々な解析ができそうですね。


ここまでのコードをまとめたものがこちらです。
```python:Python
from pymatgen.ext.matproj import MPRester
API_KEY = "YOUR_API_KEY"
with MPRester(API_KEY) as m:
    material_ids = m.get_material_ids("Fe2O3") # Fe2O3の組成を持つデータのIDリスト
    first_entry = m.get_entry_by_material_id(material_ids[0]) # IDリストの一つ目のIDを使って、データベースの情報を表示
    print(first_entry) 
    structure = m.get_structure_by_material_id(material_ids[0])
    print(structure)
    print(structure.lattice)
```
:::note warn
APIキーの入力を忘れないようにしてください。正しく入力されていないとエラーが表示されます。
:::

# まとめ
以上、pymatgenのインストールし環境を構築し、Materials Projectからデータを取得し活用する方法を解説しました。pymatgenを活用することで、Materials Projectの膨大なデータを効率的に利用して様々な解析を行うことができそうですね。

# 参考文献
- [pymatgen](https://pymatgen.org/index.html)
- [Materials Project](https://next-gen.materialsproject.org/)
- [【初心者向け】Anacondaで仮想環境を作ってみる](https://qiita.com/ozaki_physics/items/985188feb92570e5b82d)