Querying Data from the Materials Project API Client
Description
Materials Project (MP) is an open-source database for inorganic materials. Using the MP API client, you can conveniently access and query the MP database from Python.
Finding by id
First, you need your API Key, so sign up before proceeding. You can pass desired material ids or property-based conditions as inputs to mpr.materials.summary.search() to retrieve data. For example, the following code retrieves summary information for the materials mp-2209 and mp-29658. The retrieved docs is a list of MPDataDoc objects, and you can access each material’s information via the attributes of an MPDataDoc.
from mp_api.client import MPRester
my_key = "asdfsfasdfdsfsafasf"
with MPRester(my_key) as mpr:
docs = mpr.materials.summary.search(
material_ids=["mp-2209", "mp-29658"]
)
>>> type(docs[0])
<class 'mp_api.client.core.client.MPDataDoc'>
>>> [doc.material_id for doc in docs]
[MPID(mp-29658), MPID(mp-2209)]
>>> [doc.formula_pretty for doc in docs]
['ZrNiH3', 'CeGa2']
From the result above, docs[0] is the document containing information for $\ce{ZrNiH_{3}}$ with id mp-29658, and docs[1] is the document containing information for $\ce{CeGa_{2}}$ with id mp-2209. Note that this is independent of the order of material_ids passed to search. The full information contained in docs[0] is as follows.
You can access desired attributes from each MPDataDoc as shown below.
>>> doc = docs[0]
>>> doc.formula_pretty #화학식
'ZrNiH3'
>>> doc.nsites #원자수
10
>>> doc.band_gap #밴드갭
0.0
>>> doc.energy_per_atom #원자당 에너지
-5.438467611000001
>>> doc.is_metal #금속여부
True
To check all possible attributes, call mpr.materials.summary.available_fields.
>>> mpr.materials.summary.available_fields
['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', 'bulk_modulus', 'shear_modulus', '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', 'database_IDs']
Sorted alphabetically
band_gap
bandstructure
builder_meta
bulk_modulus
cbm
chemsys
composition
composition_reduced
database_IDs
decomposes_to
density
density_atomic
deprecated
deprecation_reasons
dos
dos_energy_down
dos_energy_up
e_electronic
e_ij_max
e_ionic
e_total
efermi
elements
energy_above_hull
energy_per_atom
equilibrium_reaction_energy_per_atom
es_source_calc_id
formation_energy_per_atom
formula_anonymous
formula_pretty
grain_boundaries
has_props
has_reconstructed
homogeneous_poisson
is_gap_direct
is_magnetic
is_metal
is_stable
last_updated
material_id
n
nelements
nsites
num_magnetic_sites
num_unique_magnetic_sites
ordering
origins
possible_species
property_name
shape_factor
shear_modulus
structure
surface_anisotropy
symmetry
task_ids
theoretical
total_magnetization
total_magnetization_normalized_formula_units
total_magnetization_normalized_vol
types_of_magnetic_species
uncorrected_energy_per_atom
universal_anisotropy
vbm
volume
warnings
weighted_surface_energy
weighted_surface_energy_EV_PER_ANG2
weighted_work_function
xas
Finding by filter
If you want to obtain materials that satisfy specific conditions, pass those conditions as inputs to search. Note that the attribute names in MPDataDoc and the names used as inputs to search may not match exactly.
For example, to find materials with number of atoms >= 4 and band gap >= 2 eV, write the code as follows. This returns 36,490 structure entries.
>>> with MPRester(my_key) as mpr:
... docs = mpr.materials.summary.search(
... num_sites=(4, None),
... band_gap=(2, None)
... )
Retrieving SummaryDoc documents: 100%|██████████████████████████████████████████| 36490/36490 [01:10<00:00, 517.50it/s]
The full list of filters you can use with search is shown below.
Sorted alphabetically
band_gap
chemsys
crystal_system
density
deprecated
e_electronic
e_ionic
e_total
efermi
elastic_anisotropy
elements
energy_above_hull
equilibrium_reaction_energy
exclude_elements
formation_energy
formula
g_reuss
g_voigt
g_vrh
has_props
has_reconstructed
is_gap_direct
is_metal
is_stable
k_reuss
k_voigt
k_vrh
magnetic_ordering
material_ids
n
nelements
num_elements
num_sites
num_magnetic_sites
num_unique_magnetic_sites
piezoelectric_modulus
poisson_ratio
possible_species
shape_factor
spacegroup_number
spacegroup_symbol
surface_energy_anisotropy
theoretical
total_energy
total_magnetization
total_magnetization_normalized_formula_units
total_magnetization_normalized_vol
uncorrected_energy
volume
weighted_surface_energy
weighted_work_function
include_gnome
num_chunks
chunk_size
all_fields
fields
Among these, you can use fields to specify which attributes to include in the returned data. For example, from the materials found by the above conditions, to save only the number of atoms, band gap, energy per atom, and id, write the code as follows. The resulting MPDataDoc objects will contain only the specified attributes, and the names of the other attributes will be stored in a list called fields_not_requested.
>>> with MPRester(my_key) as mpr:
... docs = mpr.materials.summary.search(
... num_sites=(4, None), band_gap=(2, None),
... fields=["nsites", "band_gap", "energy_per_atom", "material_id"]
... )
Retrieving SummaryDoc documents: 100%|█████████████████████████████████████████| 36490/36490 [00:11<00:00, 3171.23it/s]
>>> docs[0]
MPDataDoc<SummaryDoc>(
nsites=5,
material_id=MPID(mp-11107),
energy_per_atom=-8.354914895999997,
band_gap=3.522599999999999,
fields_not_requested=['builder_meta', 'elements', 'nelements', 'composition', 'composition_reduced', 'formula_pretty', 'formula_anonymous', 'chemsys', 'volume', 'density', 'density_atomic', 'symmetry', 'property_name', 'deprecated', 'deprecation_reasons', 'last_updated', 'origins', 'warnings', 'structure', 'task_ids', 'uncorrected_energy_per_atom', 'formation_energy_per_atom', 'energy_above_hull', 'is_stable', 'equilibrium_reaction_energy_per_atom', 'decomposes_to', 'xas', 'grain_boundaries', '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', 'bulk_modulus', 'shear_modulus', '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', 'database_IDs']
)