新版和老版Materials Project API使用指南

Posted on Edited on In Views: Symbols count in article: 7.2k

介绍

Materials Project是一个开放的材料数据库，她提供了很多理论预测和实验上观察到的材料的计算性质，并且以网页的形式提供了查询的接口。最近Materials Project官方网站消息显示即将迎来新版本，同时也推出了新版本的预览版。以下分别是老版和新版（预览）的地址和首页：

前言

最近闲来无事，又捣鼓起来了Materials Project，主要是想要利用Materials Project提供的API来批量获取某些材料的某些性质，然后训练和测试一些简单的模型。由于之前使用过老版的API，所以对于老版的API调用还是比较熟悉的，但是新版之前没有使用过，花了一天时间探索之后，发现新版和老版的API调用上既有相同的地方，也有不同的地方，所以这里打算写一篇文章来简单地探讨一下，同时也可以作为入门的快速指南。当然值得一提的是，Materials Project本身博大精深，包含材料各个方面的数据，这篇文章的内容只是初窥一隅。

前期准备

不管是新版还是老版的Materials Project，要调用首先需要获取API Key,获取方式大同小异，首先用账号登录网站，然后在Dashboard页面生成API Key，如下图：

old-key new-key

老版API调用

1.MPRester类简介

老版API调用方法已经加入到了Pymatgen的模块之中，Pymatgen是一个高通量计算的Python模块，几乎所有的API调用过程都是通过pymatgen.ext.matproj模块下的MPRester类来实现的。MPRester类有四个参数：

  • api_key：字符串类型，传入之前获得的API Key
  • endpoint：字符串类型，传入访问数据库的入口url
  • notify_db_version：布尔类型，决定是否将访问时获得的数据库版本信息记录在本地文件中
  • include_user_agent：布尔类型，决定在发送HTTP请求时是否发送pymatgen版本信息和访问设备信息

2.MPRester类的一些常用函数简介

MPRester类封装了几乎所有调用数据库的函数，以下对一些比较常用的函数做一些说明：

  • get_bandstructure_by_material_id(material_id, line_mode=True)：根据material_id获取能带结构

note：Materials Project中每个材料都对应一个唯一的id，相当于材料的身份证号码，知道了material id就能通过调用函数来获取材料的所有数据

  • get_doc(materials_id)：根据mp-id获取材料所有的数据的文档，json格式的文档
  • get_dos_by_material_id(material_id)：根据mp-id获取材料的态密度
  • get_phonon_bandstructure_by_material_id(material_id)：根据mp-id获取材料的声子谱
  • get_phonon_dos_by_material_id(material_id)：根据mp-id获取材料的声子态密度
  • get_entries(chemsys_formula_id_criteria, compatible_only=True, inc_structure=None, property_data=None, conventional_unit_cell=False, sort_by_e_above_hull=False)：根据化学系统、化学式、mp-id或所有的标准获取相应材料的计算数据列表
  • get_entries_in_chemsys(elements, compatible_only=True, inc_structure=None, property_data=None, conventional_unit_cell=False)：衍生自get_entries函数，获取化学系统的的计算数据
  • get_entry_by_material_id(material_id, compatible_only=True, inc_structure=None, property_data=None, conventional_unit_cell=False)：同上
  • get_structure_by_material_id(material_id, final=True, conventional_unit_cell=False)：根据mp-id获取材料的结构
  • get_structures(chemsys_formula_id, final=True)：根据化学组成获取结构列表

3.MPRester类的两个重要函数：

get_materials_ids(chemsys_formula)

该函数提供了根据对应化学式获取相应的mp-id的功能，可以用于搜索特定组成或化学式的材料在Materials Project中的mp-id，chemsys_formula参数为字符串类型，可以是指定元素类别，如"Fe-Li-O"表示获取所有包含Li、Fe、O三种元素的材料的mp-id；也可以是指定化学式，如"Fe2O3"表示获取所有化学式为Fe2O3的材料的mp-id，该函数返回列表类型，列表中包含了所有的mp-id。

get_data(chemsys_formula_id, data_type=‘vasp’, prop=‘’)

不同于之前一次性获取材料的所有数据，该函数能够灵活地获得某一材料地某个（些）特定数据，其有三个关键参数：

  • chemsys_formula_id：字符串类型，传入对应材料的元素组成，化学式或者mp-id
  • data_type：返回的数据类型，可以传入"vasp"或"exp"
  • prop：需要获取的数据，字符串类型，可以填入的参数为(‘energy’, ‘energy_per_atom’, ‘volume’, ‘formation_energy_per_atom’, ‘nsites’, ‘unit_cell_formula’, ‘pretty_formula’, ‘is_hubbard’, ‘elements’, ‘nelements’, ‘e_above_hull’, ‘hubbards’, ‘is_compatible’, ‘spacegroup’, ‘band_gap’, ‘density’, ‘icsd_id’, ‘cif’)，如果为空即为获取部分常用的性质数据。

4.代码实战

下面为实际调用的python代码，完成的是获取所有不同结构的Si单质对应的mp-id，然后根据mp-id获取对应材料的一些性质。

1
2
3
4
5
6
7
8
9
10
11
from pymatgen.ext.matproj import MPRester

my_api_key = "your api key"
with MPRester(api_key=my_api_key) as mpr:
    ls_mat_ids = mpr.get_materials_ids(chemsys_formula="Si")
    for mat_id in ls_mat_ids:
        mat_info = []
        mat_formula = mpr.get_data(chemsys_formula_id=mat_id, prop="pretty_formula")
        mat_spacegroup = mpr.get_data(chemsys_formula_id=mat_id, prop="spacegroup")
        mat_band_gap = mpr.get_data(chemsys_formula_id=mat_id, prop="band_gap")
        print(mat_id, mat_formula[0]['pretty_formula'], mat_spacegroup[0]['spacegroup']['symbol'], mat_band_gap[0]['band_gap'])

以下为运行结果：
old-result

新版API调用

新版本Materials Project在API调用上与老版本既有相同的地方，也有不同的地方。官网手册上对二者作了对比：difference

1.安装mp-api包

首先一个显著不同的是，新版本Materials Project在调用上使用的是Python的mp-api模块，这一模块并不包含在pymatgen中（官网补充说明：可能之后会并入pymatgen），而是作为独立的模块，需要重新安装，安装非常容易，使用pip工具就可以：

1
pip install mp-api

2.MPRester类的框架

与老版本一样，具体的调用函数是封装在MPRester类中的。不同的是，新版中将材料的各个性质分别封装在各个子类中，做了进一步的归档，需要查询某个性质时可以通过这些子类提供的函数来做进一步的查询，具体有：

  • bonds：包含根据pymatgen中定义的近邻策略计算的化学键信息
  • charge_density：包含材料的电荷密度信息
  • dielectric：包含材料的介电性质
  • doi：特定材料的参考文献的doi
  • elasticity：包含材料的弹性数据
  • electronic_structure：包含材料的核心电子结构信息
  • eos：能量-体积状态的拟合方程
  • fermi：材料的费米面信息
  • grain_boundary：包含晶界能，解离能
  • insertion_electrodes：插入的电极
  • magnetism：从计算结果中得到的磁性数据
  • materials：包含材料的一些核心信息
  • molecules：与电池电解质相关的分子
  • oxidation_states：根据结构计算的氧化态
  • phonon：声子谱和声子态密度数据
  • piezoelectric：材料的介电信息
  • provenance：提供材料的证明材料，主要包括材料是否是理论预测的，相关的ICSD id，所在的参考文献
  • robocrys：提供材料的机器人晶体学家(???)描述信息
  • similarity：包含相似结构的信息数据
  • substrates：给定材料的可能生长基底的信息
  • summary：有关材料及其属性的摘要信息，较为常用
  • surface_properties：包含材料的表面性质相关的信息
  • synthesis：包含材料的合成配方数据和附加关键字的搜索结果信息
  • tasks：为Materials Project提供数据的相关VASP计算的详细信息
  • thermo：与热相关的性质
  • xas：包含XAS谱的相关信息

3.子类的相关函数调用

这些子类提供的调用方法又各有不同，传入的参数也有所差别，具体使用时需要参考官方文档。由于我在使用时只用到了这两个子类：summary和materials，所以以下详细介绍这两个子类。

summary子类

以下引自官网：summary提供了某一材料的合并数据，整合了很多其它子类包含的性质，当材料的性质空间包含很多时，使用summary非常有效，注意Materials Project中每个材料都有一份独一无二的summary文档。summary子类中常用的函数有两个，即：get_data_by_id和search_summary_docs,下面分别介绍：

  • get_data_by_id：包含三个参数，material_id(必要)、fields和all_fields，其中fields是一串以逗号分隔的字符串，说明需要获取的summary文档中需要包含的性质，具体的字段有：builder_meta nsites elements nelements composition composition_reduced formula_pretty formula_anonymous chemsys volume density density_atomic symmetry property_name material_id deprecated deprecation_reasons last_updated origins warnings structure task_ids uncorrected_energy_per_atom energy_per_atom formation_energy_per_atom energy_above_hull is_stable equilibrium_reaction_energy_per_atom decomposes_to xas grain_boundaries band_gap cbm vbm efermi is_gap_direct is_metal es_source_calc_id bandstructure dos dos_energy_up dos_energy_down is_magnetic ordering total_magnetization total_magnetization_normalized_vol total_magnetization_normalized_formula_units num_magnetic_sites num_unique_magnetic_sites types_of_magnetic_species k_voigt k_reuss k_vrh g_voigt g_reuss g_vrh universal_anisotropy homogeneous_poisson e_total e_ionic e_electronic n e_ij_max weighted_surface_energy_EV_PER_ANG2 weighted_surface_energy weighted_work_function surface_anisotropy shape_factor has_reconstructed possible_species has_props theoretical，具体含义可以参考英文意义和网站上展示的数据来理解，这里需要特别说明的一点是：相比于老版，新版Materials Project对材料作了是否实验上观察到的划分，并且设置了一个变量来指示，因此可以非常容易知道哪些是实验上已经合成出来的，这个变量就是以上fields中的theoretical字段，是布尔值，True表示材料是理论预测的，False表示材料已经实验观察到了。最后一个参数是布尔类型，如果设置为True，那么请求的summary文档会包含以上所有性质。
  • search_summary_docs：其包含的参数非常多，具体参考官网,其中一些常用的参数formula、chemsys、crystal_system分别为指定化学式、化学成分和晶系来搜索对应的文档，其它参数用到可以再具体查询。
materials子类

以下引自官网：materials提供了材料在Materials Project数据库中的核心信息，其中mp-id是材料的唯一标识符，这里核心信息指：晶体结构、密度、化学式以及与计算相关的task_id,不包含形成能和带隙等信息。和summary子类一样，其较为核心的同样是以上提到的两个函数，并且传入的参数也类似，这里不再赘述，值得一提的是，这里的fields参数包含的字段相对于summary中更少，具体是：builder_meta nsites elements nelements composition composition_reduced formula_pretty formula_anonymous chemsys volume density density_atomic symmetry material_id structure deprecated deprecation_reasons initial_structures task_ids deprecated_tasks calc_types last_updated created_at origins warnings。

4.note

当然，新版的MPRester类中也提供了一些不需要通过子类来调用的函数，这些函数的用法大都与老版的相应同名函数的用法相同，如get_materials_ids函数、get_data函数等。

5.代码实战

这里的代码完成的同样是获取不同结构Si单质的相应数据，同时添加了新版的一个新的特性，即判断材料是否实验上观察到。以下为代码：

1
2
3
4
5
6
7
8
from mp_api import MPRester

my_api_key = "your api key"
with MPRester(api_key=my_api_key) as mpr:
    ls_mat_ids = mpr.get_materials_ids(chemsys_formula="Si")
    for mat_id in ls_mat_ids:
        mat_summary = mpr.summary.get_data_by_id(mat_id,fields="formula_pretty,symmetry,band_gap,theoretical")
        print(mat_id, mat_summary.formula_pretty, mat_summary.symmetry.symbol, mat_summary.band_gap, mat_summary.theoretical)

以下为代码的运行结果：new-result