Materials Project API

What Materials Project API is

mp-api is the Python client for the Materials Project, the database of computed properties for inorganic materials. It returns structures, energies above hull, band gaps, elastic tensors and other stored quantities by material id or by query. On the map it serves the quantities it retrieves. It computes none of them.

WebsiteRepositoryOn the mapAll codesLicense: modified BSD (BSD-3-Clause)

In more detail

What the Materials Project stores and how it is made

The project computes properties of known inorganic compounds, mostly ICSD structures, with VASP. FireWorks runs the workflows at supercomputing centers and custodian repairs failed runs by rule-based fixes to cluster and convergence parameters, so a metal and an insulator get different workflows without human steps. At publication the database held over 33 000 compounds from over 15 million CPU-hours. Automated checks compare oxidation states, cell volumes and bond lengths with experiment and flag outliers, van der Waals layered compounds for instance, and a Report Issues button collects user corrections (Jain 2013).

The Materials API

The API follows REST principles. Each material is a URL such as materialsproject.org/rest/v1/[unique-id], an HTTP verb acts on it, and the answer is JSON. The project launched it so that users could pull large datasets for data mining or combine local data with the project's, which the web apps cannot serve efficiently. At the time transfer was one way, with two-way submission of structures and experimental data planned. pymatgen carries a high-level interface to the API, and pymatgen-db builds local Materials Project-like MongoDB databases (Jain 2013).

Studies built on the API

Sun 2016 retrieved 29,902 provenance-filtered ICSD phases and found 50.5% metastable with a median of 15 meV/atom and a 90th percentile of 67 meV/atom. Aykol 2018 took every polymorph entry in the database for 41 systems and compared them with ab initio amorphous limits. Bartel 2020 queried all entries with formation enthalpy below 1 eV/atom on July 26, 2019 through the MP API, 85,014 formulas, and noted that the decomposition energies used for training and testing change as new stable materials enter the database.

What it computes on the map

13 quantities, drawn by tier with the data flow between them. Dashed boxes are intermediate quantities. Select one for its formula and the other codes that compute it.

Each quantity with the interface the representation records.

• BandGapmpr.materials.summary.search(fields=['band_gap']).band_gap, eV; also bs.get_band_gap()['energy'] from the electronic-structure endpointev
• BulkModulusmpr.materials.elasticity.search().bulk_modulus.vrh, GPa (nested {voigt, reuss, vrh} dict)GPa
• DielectricTensormpr.materials.summary.search(fields=['e_electronic']).e_electronic, dimensionless (electronic dielectric constant)dimensionless
• ElasticConstantsmpr.materials.elasticity.search().elastic_tensor.{raw, ieee_format} (Voigt 6x6), GPaGPa
• EnergyAboveHullmpr.materials.summary.search(fields=['energy_above_hull']).energy_above_hull, eV/atom; also mpr.materials.thermo.search(thermo_types=[...])ev_per_atom
• FormationEnergympr.materials.summary.search(fields=['formation_energy_per_atom']).formation_energy_per_atom, eV/atomev_per_atom
• MagneticMomentmpr.materials.magnetism.search().magmoms[i] (per-site list, mu_B); MagnetismDoc.magmomsmu_B
• PoissonRatiompr.materials.elasticity.search().homogeneous_poisson, dimensionlessdimensionless
• ShearModulusmpr.materials.elasticity.search().shear_modulus.vrh, GPa (nested {voigt, reuss, vrh} dict)GPa
• Structurempr.materials.summary.search(fields=['structure']).structure / mpr.materials.get_structure_by_material_id(material_id) -> pymatgen Structure, angstrom
• SurfaceEnergympr.materials.summary.search(fields=['weighted_surface_energy']).weighted_surface_energy, J/m^2 (Wulff-weighted aggregate)J_per_m2
• Voltagempr.materials.insertion_electrodes.search(working_ion=...).average_voltage, Vvolt
• YoungsModulusmpr.materials.elasticity.search().young_modulus, SI Pa (DIVIDE by 1e9 for GPa)Pa

References

The code

The papers that describe the code; cite them when you use it.

1. A. Jain, S. P. Ong, G. Hautier et al., Commentary: The Materials Project: A materials genome approach to accelerating materials innovation, APL Materials, 2013. doi.org/10.1063/1.4812323

Applications

Highly cited studies that cite the code, with a few picked by hand.

1. W. Sun, S. T. Dacek, S. P. Ong et al., The thermodynamic scale of inorganic crystalline metastability, Science Advances, 2016. doi.org/10.1126/sciadv.1600225
2. M. Aykol, S. S. Dwaraknath, W. Sun et al., Thermodynamic limit for synthesis of metastable inorganic materials, Science Advances, 2018. doi.org/10.1126/sciadv.aaq0148
3. C. J. Bartel, A. Trewartha, Q. Wang et al., A critical examination of compound stability predictions from machine-learned formation energies, npj Computational Materials, 2020. doi.org/10.1038/s41524-020-00362-y

How to cite

A. Jain, S. P. Ong, G. Hautier, et al., Commentary: The Materials Project: A materials genome approach to accelerating materials innovation, APL Mater. 1, 011002 (2013)

doi.org/10.1063/1.4812323