Practical: Materials Project

In this practical, we will use the Materials Project API to access information about materials. The Materials Project is a database of materials properties that is maintained by the Lawrence Berkeley National Laboratory. The database contains information about the properties of a large number of materials, including their crystal structures, band structures, and thermodynamic properties.

Register for a Materials Project API Key¶

To access the Materials Project API, you will need to register for an API key. You can register an account of Materials Project by visiting the following website: https://profile.materialsproject.org/

Then you can find your API key in the dashboard page. You should set your MP_API_KEY in the following cell.

MP_API_KEY = "your-key" # check https://next-gen.materialsproject.org/dashboard for your API key

Install the `mp_api` Package¶

We need to install mp_api package to access the Materials Project API. You can install the package using the following command:

# you can skip this if you've already installed the mp_api package.
!pip install mp_api

Python Version Problem

If you’re using Python version 3.13, you might encounter installation error. You need to reinstall a lower version of Python (e.g. 3.12). If you don’t have any problem install the package, you can skip the following steps.

First, you need to uninstall the current virtual enviornment. Open Terminal and type following command:

rm -rf .venv

Then recreate a new virtual enviornment with Python version, e.g. 3.12.

python3.12 -m venv .venv

Activate the virtual enviornment.

source .venv/bin/activate

Activate the virtual enviornment. Open Anaconda Prompt and type the following command.

pip install jupyter ase pymatgen

Then close and reopen your VS Code and try above cell again.

Querying Data from the Materials Project Database¶

We can query data from the Materials Project database using the mp_api package. The mp_api package provides a Python interface to the Materials Project API, which allows you to query the database for information about materials. The package provides a number of functions for querying the database, including functions for querying materials by chemical formula, by material ID, and by crystal structure.

To query data from the data base, we need to import the MPRester class from the mp_api package. We can then create an instance of the MPRester class, passing our API key as an argument to the constructor. We can then use the instance to query the database for information about materials.

In the example below, we are searching data using the material_ids.

Query Materials by Material ID¶

You can query the Materials Project database for information about a material by its material ID. The material ID is a unique identifier that is assigned to each material in the database. You can find the material ID for a material by searching for the material on the Materials Project website.

from mp_api.client import MPRester

# Pass your API key directly as an argument.
with MPRester(MP_API_KEY) as mpr:
    docs = mpr.materials.summary.search(
        material_ids=["mp-149", "mp-13", "mp-2131"]
    )

Show the Available Fields¶

We can check the available properties from mpr.materials.summary.available_fields.

print(f"Available fields: {mpr.materials.summary.available_fields}")

# Print out the data (some) for each material
for example_doc in docs:
    print("\n--------------------")
    print(f"Material ID: {example_doc.material_id}")
    print(f"Theoretical? {example_doc.theoretical}") # whether this structure is a purely theoretical structure or  not (also exist in experiment)
    print(f"Formula: {example_doc.formula_pretty}")

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']

--------------------
Material ID: mp-13
Theoretical? False
Formula: Fe

--------------------
Material ID: mp-2131
Theoretical? False
Formula: SrN6

--------------------
Material ID: mp-149
Theoretical? False
Formula: Si

Customize the Search Function¶

We can customize our search in search() function. For example, we can search for materials with a specific chemical formula, or we can search for materials with specific density. Please note that sometimes, the search may return lots of results, it’s better to save these results into a json file.

Chemsys Search¶

You can use chemsys to search for materials with specific elements. For example, Fe-O will search for materials with Iron and Oxygen. You can also use fields to specify the properties you want to get. You can find more information about the search in the Materials Project API documentation.

with MPRester(MP_API_KEY) as mpr:
    docs = mpr.materials.summary.search(
        chemsys="Li-Fe-P-O", is_stable=True,
        # fields=["material_id", "volume", "elements","structure"]
    )

# dump results to a json file
import json
with open('materials_data.json', 'w') as f:
    json.dump([doc.dict() for doc in docs], f, indent=4)

You can use wildcard * to search for all elements. You can also put formula pattern in search. For example, ABO3 will search for ternary materials with formula ending with O3, structure with perovskite related composition.

with MPRester(MP_API_KEY) as mpr:
    docs = mpr.materials.summary.search(
        chemsys="O-*-*", formula="ABO3",
        fields=["material_id", "band_gap","composition", "energy_above_hull"], 
        energy_above_hull=[0,0.01], band_gap=[0.5, 1.5]
    )
    mpid_bgap_dict = {doc.material_id: [doc.band_gap, doc.composition, doc.energy_above_hull] for doc in docs}

print(f"Materials found: {len(mpid_bgap_dict)}")
for mpid, (bgap, composition, energy_above_hull) in mpid_bgap_dict.items():
    print(f"Material ID: {mpid}, Band gap: {bgap:.2f} eV, Composition: {composition}, Energy above hull: {energy_above_hull*1000:.2f} meV")

Materials found: 71
Material ID: mp-1221539, Band gap: 0.91 eV, Composition: Mo4 Br12 O4, Energy above hull: 0.00 meV
Material ID: mp-558934, Band gap: 1.27 eV, Composition: Hg36 Cl12 O12, Energy above hull: 4.59 meV
Material ID: mp-29019, Band gap: 0.63 eV, Composition: Rb18 I6 O6, Energy above hull: 0.00 meV
Material ID: mp-505212, Band gap: 1.33 eV, Composition: Cs6 Au2 O2, Energy above hull: 0.00 meV
Material ID: mp-28166, Band gap: 0.89 eV, Composition: K3 Br1 O1, Energy above hull: 0.00 meV
Material ID: mp-28171, Band gap: 1.03 eV, Composition: K3 I1 O1, Energy above hull: 0.00 meV
Material ID: mp-9200, Band gap: 0.56 eV, Composition: K3 Au1 O1, Energy above hull: 0.00 meV
Material ID: mp-673798, Band gap: 1.03 eV, Composition: K6 Cl2 O2, Energy above hull: 7.48 meV
Material ID: mp-546285, Band gap: 0.82 eV, Composition: Nb2 I6 O2, Energy above hull: 0.00 meV
Material ID: mp-11649, Band gap: 0.51 eV, Composition: Ca12 Si4 O4, Energy above hull: 0.71 meV
Material ID: mp-572291, Band gap: 1.08 eV, Composition: K12 Cl4 O4, Energy above hull: 0.40 meV
Material ID: mp-755428, Band gap: 1.22 eV, Composition: Rb12 Cl4 O4, Energy above hull: 0.00 meV
Material ID: mp-757636, Band gap: 0.96 eV, Composition: Nb8 Tl8 O24, Energy above hull: 0.00 meV
Material ID: mp-545482, Band gap: 1.06 eV, Composition: Pd2 Se2 O6, Energy above hull: 0.00 meV
Material ID: mp-1283250, Band gap: 1.14 eV, Composition: Ba4 Co4 O12, Energy above hull: 1.06 meV
Material ID: mp-1542758, Band gap: 1.31 eV, Composition: Sr2 Mo2 O6, Energy above hull: 0.00 meV
Material ID: mp-546684, Band gap: 0.82 eV, Composition: Pd2 Se2 O6, Energy above hull: 4.67 meV
Material ID: mp-1106094, Band gap: 0.88 eV, Composition: K4 C4 O12, Energy above hull: 0.00 meV
Material ID: mp-607467, Band gap: 1.10 eV, Composition: Ca4 Mo4 O12, Energy above hull: 0.00 meV
Material ID: mp-727242, Band gap: 0.67 eV, Composition: Na4 C4 O12, Energy above hull: 1.81 meV
Material ID: mp-755893, Band gap: 0.67 eV, Composition: Ca4 Bi4 O12, Energy above hull: 0.00 meV
Material ID: mp-755478, Band gap: 0.77 eV, Composition: Cd2 Bi2 O6, Energy above hull: 4.83 meV
Material ID: mp-1288145, Band gap: 0.95 eV, Composition: La2 Co2 O6, Energy above hull: 0.00 meV
Material ID: mp-20569, Band gap: 0.88 eV, Composition: Mn2 Sn2 O6, Energy above hull: 0.00 meV
Material ID: mp-23054, Band gap: 1.10 eV, Composition: Na2 Bi2 O6, Energy above hull: 0.00 meV
Material ID: mp-754246, Band gap: 1.11 eV, Composition: Ti2 Sn2 O6, Energy above hull: 9.59 meV
Material ID: mp-754329, Band gap: 0.98 eV, Composition: Cd2 Sn2 O6, Energy above hull: 1.07 meV
Material ID: mp-676262, Band gap: 0.98 eV, Composition: Ta8 Tl8 O24, Energy above hull: 0.00 meV
Material ID: mp-23501, Band gap: 1.28 eV, Composition: Fe2 Bi2 O6, Energy above hull: 1.63 meV
Material ID: mp-30284, Band gap: 1.24 eV, Composition: Hg2 As2 O6, Energy above hull: 0.00 meV
Material ID: mp-18840, Band gap: 0.90 eV, Composition: Ba3 Mn3 O9, Energy above hull: 0.00 meV
Material ID: mp-675227, Band gap: 0.87 eV, Composition: Ba5 Mn5 O15, Energy above hull: 1.78 meV
Material ID: mp-1120755, Band gap: 0.66 eV, Composition: Na2 C2 O6, Energy above hull: 0.00 meV
Material ID: mp-19051, Band gap: 1.00 eV, Composition: La4 Co4 O12, Energy above hull: 3.32 meV
Material ID: mp-19097, Band gap: 1.48 eV, Composition: Fe2 B2 O6, Energy above hull: 0.00 meV
Material ID: mp-19001, Band gap: 0.90 eV, Composition: Sr4 Mn4 O12, Energy above hull: 3.06 meV
Material ID: mp-19138, Band gap: 1.47 eV, Composition: Ba2 Ni2 O6, Energy above hull: 0.00 meV
Material ID: mp-557535, Band gap: 0.84 eV, Composition: Ba8 Mn8 O24, Energy above hull: 1.22 meV
Material ID: mp-8098, Band gap: 1.34 eV, Composition: In2 Ga2 O6, Energy above hull: 0.00 meV
Material ID: mp-1045305, Band gap: 1.14 eV, Composition: Ca4 Mo4 O12, Energy above hull: 9.69 meV
Material ID: mp-1178212, Band gap: 0.86 eV, Composition: Fe4 Sn4 O12, Energy above hull: 0.00 meV
Material ID: mp-1279343, Band gap: 0.96 eV, Composition: Co2 Ni2 O6, Energy above hull: 0.37 meV
Material ID: mp-861502, Band gap: 0.99 eV, Composition: Ac1 Fe1 O3, Energy above hull: 0.00 meV
Material ID: mp-935811, Band gap: 1.41 eV, Composition: K1 Nb1 O3, Energy above hull: 7.73 meV
Material ID: mp-977455, Band gap: 0.92 eV, Composition: Pa1 Ag1 O3, Energy above hull: 0.00 meV
Material ID: mp-756933, Band gap: 0.66 eV, Composition: Ta4 Tl4 O12, Energy above hull: 4.27 meV
Material ID: mp-1205366, Band gap: 1.09 eV, Composition: Lu4 Rh4 O12, Energy above hull: 0.00 meV
Material ID: mp-1207705, Band gap: 0.96 eV, Composition: Tm4 Rh4 O12, Energy above hull: 0.00 meV
Material ID: mp-1209329, Band gap: 1.30 eV, Composition: Pr4 V4 O12, Energy above hull: 0.00 meV
Material ID: mp-1212108, Band gap: 0.96 eV, Composition: Ho4 Rh4 O12, Energy above hull: 0.00 meV
Material ID: mp-1212884, Band gap: 0.89 eV, Composition: Dy4 Rh4 O12, Energy above hull: 0.00 meV
Material ID: mp-1213022, Band gap: 0.96 eV, Composition: Er4 Rh4 O12, Energy above hull: 0.00 meV
Material ID: mp-19012, Band gap: 1.13 eV, Composition: Ca4 Mo4 O12, Energy above hull: 6.36 meV
Material ID: mp-19802, Band gap: 1.42 eV, Composition: Tb4 Co4 O12, Energy above hull: 0.00 meV
Material ID: mp-20079, Band gap: 0.93 eV, Composition: Ca4 Pb4 O12, Energy above hull: 2.45 meV
Material ID: mp-20489, Band gap: 0.79 eV, Composition: Sr4 Pb4 O12, Energy above hull: 0.00 meV
Material ID: mp-22137, Band gap: 1.19 eV, Composition: Dy4 Co4 O12, Energy above hull: 9.31 meV
Material ID: mp-22283, Band gap: 0.91 eV, Composition: Dy4 Fe4 O12, Energy above hull: 6.33 meV
Material ID: mp-22341, Band gap: 1.08 eV, Composition: Pr4 Fe4 O12, Energy above hull: 0.00 meV
Material ID: mp-3317, Band gap: 0.73 eV, Composition: Sm4 Rh4 O12, Energy above hull: 0.00 meV
Material ID: mp-4582, Band gap: 0.65 eV, Composition: Nd4 Rh4 O12, Energy above hull: 0.00 meV
Material ID: mp-4789, Band gap: 0.60 eV, Composition: Pr4 Rh4 O12, Energy above hull: 0.00 meV
Material ID: mp-5163, Band gap: 0.59 eV, Composition: La4 Rh4 O12, Energy above hull: 0.00 meV
Material ID: mp-541129, Band gap: 1.03 eV, Composition: Nd4 V4 O12, Energy above hull: 0.00 meV
Material ID: mp-554811, Band gap: 1.44 eV, Composition: Tb4 V4 O12, Energy above hull: 0.00 meV
Material ID: mp-562779, Band gap: 1.45 eV, Composition: Er4 Co4 O12, Energy above hull: 0.00 meV
Material ID: mp-5692, Band gap: 0.87 eV, Composition: Tb4 Rh4 O12, Energy above hull: 0.00 meV
Material ID: mp-4784, Band gap: 1.30 eV, Composition: Ca2 Pt2 O6, Energy above hull: 0.00 meV
Material ID: mp-1178513, Band gap: 0.67 eV, Composition: Ba2 Sn2 O6, Energy above hull: 0.65 meV
Material ID: mp-1101462, Band gap: 0.95 eV, Composition: Nb8 Tl8 O24, Energy above hull: 1.37 meV
Material ID: mp-4342, Band gap: 1.48 eV, Composition: K1 Nb1 O3, Energy above hull: 1.19 meV

Get Properties¶

Get Structure¶

You can get the structure of the material using get_structure_by_material_id() function. It will return a pymatgen.core.Structure object. You can save the structure to a cif file using structure.to() function.

from mp_api.client import MPRester

with MPRester(MP_API_KEY) as mpr:
    structure = mpr.materials.get_structure_by_material_id(material_id="mp-149")

structure.to(filename="mp-149.cif")

"# generated using pymatgen\ndata_Si\n_symmetry_space_group_name_H-M   'P 1'\n_cell_length_a   3.84927840\n_cell_length_b   3.84927941\n_cell_length_c   3.84927800\n_cell_angle_alpha   60.00001213\n_cell_angle_beta   60.00000347\n_cell_angle_gamma   60.00001098\n_symmetry_Int_Tables_number   1\n_chemical_formula_structural   Si\n_chemical_formula_sum   Si2\n_cell_volume   40.32952685\n_cell_formula_units_Z   2\nloop_\n _symmetry_equiv_pos_site_id\n _symmetry_equiv_pos_as_xyz\n  1  'x, y, z'\nloop_\n _atom_site_type_symbol\n _atom_site_label\n _atom_site_symmetry_multiplicity\n _atom_site_fract_x\n _atom_site_fract_y\n _atom_site_fract_z\n _atom_site_occupancy\n  Si  Si0  1  0.87500000  0.87500000  0.87500000  1\n  Si  Si1  1  0.12500000  0.12500000  0.12500000  1\n"

Thermodynamic Properties¶

You can construct a phase diagram using the queried data from Materials Project using get_phase_diagram_from_chemsys() function. Noted that the phase diagram is calculated using DFT and may not be the same as the experimental phase diagram as there is no temperature and pressure information.

from mp_api.client import MPRester
from emmet.core.thermo import ThermoType

with MPRester(MP_API_KEY) as mpr:
    
    # -- GGA/GGA+U mixed phase diagram
    pd = mpr.materials.thermo.get_phase_diagram_from_chemsys(chemsys="Cu-Au", 
                                                   thermo_type=ThermoType.GGA_GGA_U)
    
pd.get_plot(backend='plotly')

If you have encountered problem of using plotly to plot your data as backend, you can set the backend to matplotlib.

from mp_api.client import MPRester
from emmet.core.thermo import ThermoType

with MPRester(MP_API_KEY) as mpr:
    
    # -- GGA/GGA+U mixed phase diagram
    pd = mpr.materials.thermo.get_phase_diagram_from_chemsys(chemsys="Li-Fe-P-O", 
                                                   thermo_type=ThermoType.GGA_GGA_U)

Since this is a pymatgen PhaseDiagram object, you can visualize the results.

pd.get_plot(backend='plotly', show_unstable=False)