Function Repository Resource:

MaterialsProjectData

Source Notebook

Get material properties from the Materials Project database

Contributed by: Wolfram Staff

ResourceFunction["MaterialsProjectData"][crit]

obtains all available properties of the material satifying the criteria crit from the Materials Project database.

ResourceFunction["MaterialsProjectData"][crit,"prop"]

obtains the specified property "prop".

ResourceFunction["MaterialsProjectData"][crit,{"prop1","prop2",}]

obtains multiple properties.

ResourceFunction["MaterialsProjectData"][,session]

uses the specified running ExternalSessionObject session.

Details and Options

ResourceFunction["MaterialsProjectData"] is a wrapper to a part of the Python Materials Genomics (Pymatgen) package.
If the necessary Python dependencies are not installed, the first invocation of ResourceFunction["MaterialsProjectData"] can take longer than usual as the function attempts to install the necessary packages automatically, using the resource function PythonEvaluateWithDependencies.
Should the automatic installation fail, it might still be possible to install the necessary packages manually using the resource function PythonPackageInstall.
To use ResourceFunction["MaterialsProjectData"], obtain your own API key from the Materials Project website. The key must be stored as SystemCredential["MaterialsProjectAPIKey"].
In ResourceFunction["MaterialsProjectData"][crit,], crit can be one of the following:
"string"string
Molecule[…]molecule object
Entity["Chemical",]chemical entity object
exprexpression to be exported to a string in the "JSON" format
{expr,format}expression in the specified format
In the string form, crit can be a chemical formula, possibly with a wild card "*", a Materials ID, chemical system, string representing a Mongo-style dictionary and other strings accepted by the Pymatgen package.
expr is typically an association or a set of rules representing a Mongo-style dictionary.
format must be acceptable to ExportString.
prop must be a string representing one of the acceptable properties, Automatic to give a list of most common properties, or All to give a list of values of all available properties.
ResourceFunction["MaterialsProjectData"][crit] is equivalent to ResourceFunction["MaterialsProjectData"][crit,Automatic].
ResourceFunction["MaterialsProjectData"]["Properties"] gives the list of acceptable property names.
ResourceFunction["MaterialsProjectData"] returns a list of associations with keys corresponding to the specified properties.
The following options are accepted:
"Endpoint"AutomaticURL of the REST interface
"ChunkSize"500chunk size of the results from the database
"MaxTriesPerChunk"5number of times to retry fetching a given chunk
"MaterialsProjectDecode"Truewhether to try decoding Pymatgen objects
The option "Endpoint"Automatic refers to the standard URL of the Materials Project REST interface.
ResourceFunction["MaterialsProjectData"][,session] avoids the overhead of opening a new Python session for every successive call.

Examples

Basic Examples (2) 

Obtain an API key from the Materials Project website and enter it as your SystemCredential (one time only):

In[1]:=
SystemCredential["MaterialsProjectAPIKey"] = "yourAPIkey";

Get the properties of wüstite:

In[2]:=
Short[ResourceFunction["MaterialsProjectData"]["mp-18905"], 8]
Out[2]=

Scope (10) 

Get common properties of all materials matching a chemical formula specified as a string:

In[3]:=
Short /@ ResourceFunction["MaterialsProjectData"]["NaCl"]
Out[3]=

Get the specified property:

In[4]:=
ResourceFunction["MaterialsProjectData"]["NaCl", "density"]
Out[4]=

Several properties:

In[5]:=
ResourceFunction[
 "MaterialsProjectData"]["NaCl", {"material_id", "pretty_formula", "density"}]
Out[5]=

Get all of the available properties of wüstite:

In[6]:=
Short[ResourceFunction["MaterialsProjectData"]["mp-18905", All], 12]
Out[6]=

Give a material ID as a search criterion:

In[7]:=
ResourceFunction["MaterialsProjectData"]["mp-22851", "density"]
Out[7]=

Specify the search criterion as a Molecule object:

In[8]:=
(* Evaluate this cell to get the example input *) CloudGet["https://www.wolframcloud.com/obj/99f05d9e-dd62-41fc-a1a8-fc675b1927ec"]
Out[8]=

Search for properties of a chemical Entity object:

In[9]:=
ResourceFunction["MaterialsProjectData"][
 Entity["Chemical", "CarbonDioxide"], "material_id"]
Out[9]=

Use a wild card in the chemical formula:

In[10]:=
ResourceFunction["MaterialsProjectData"]["Fe*2", "material_id"]
Out[10]=

Specify the criterion as a Mongo database search string:

In[11]:=
ResourceFunction[
 "MaterialsProjectData"]["{\"band_gap\":{\"$gt\":8},\"nelements\":2}", "pretty_formula"]
Out[11]=

Give an Association corresponding to a Mongo-style query as a criterion:

In[12]:=
ResourceFunction[
 "MaterialsProjectData"][<|"band_gap" -> <|"$gt" -> 8|>, "nelements" -> 2|>, "pretty_formula"]
Out[12]=

Specify the format to export the query string:

In[13]:=
ResourceFunction[
 "MaterialsProjectData"][{<|"band_gap" -> <|"$gt" -> 8|>, "nelements" -> 2|>, "RawJSON"}, "pretty_formula"]
Out[13]=

Make several calls to the Materials Project database in the same external session:

In[14]:=
session = StartExternalSession["Python"]
Out[14]=
In[15]:=
ResourceFunction[
 "MaterialsProjectData"]["FeH*", "material_id", session]
Out[15]=
In[16]:=
ResourceFunction[
 "MaterialsProjectData"]["Fe2O3", "material_id", session]
Out[16]=

End the session:

In[17]:=
DeleteObject[session]

Options (3) 

Endpoint (2) 

Use the standard access URL of the Materials Project:

In[18]:=
ResourceFunction["MaterialsProjectData"]["FeH*", "material_id"]
Out[18]=

Specify the access URL:

In[19]:=
ResourceFunction["MaterialsProjectData"]["FeH*", "material_id", "Endpoint" -> "https://materialsproject.org/rest/v2"]
Out[19]=

ChunkSize (1) 

Setting "ChunkSize"0 is useful for retrieving simple properties, such as material IDs:

In[20]:=
ResourceFunction["MaterialsProjectData"]["FeH*", "material_id", "ChunkSize" -> 0]
Out[20]=

Applications (3) 

Obtain and plot the molecules of the selected materials:

In[21]:=
ResourceFunction[
 "MaterialsProjectData"]["LiTaO3", {"material_id", "molecule"}]
Out[21]=
In[22]:=
MoleculePlot3D[#2, PlotLabel -> {#1, #2["Formula"]}] & @@@ Values[%]
Out[22]=

Obtain a Crystallographic Information File (CIF) for the specified material:

In[23]:=
ResourceFunction["MaterialsProjectData"]["FeH*", "CIF"]
Out[23]=

Obtain the elastic tensor of the specified material:

In[24]:=
First[Flatten[
   Values[ResourceFunction["MaterialsProjectData"]["mp-3731", "elasticity"]]]]["elastic_tensor"]
Out[24]=

Possible Issues (2) 

On macOS, the installation of the underlying Pymatgen package in the system Python may fail:

In[25]:=
ResourceFunction["MaterialsProjectData"]["mp-18905"]
Out[26]=
In[27]:=
ResourceFunction["FindPythonExecutable"][]
Out[28]=

Use a Python version installed with Homebrew, for instance using pyenv:

In[29]:=
RegisterExternalEvaluator["Python", "/Users/admin/.pyenv/shims/python"]
Out[29]=
In[30]:=
ResourceFunction["MaterialsProjectData"]["mp-18905"] // Short
Out[30]=

Version History

  • 2.1.0 – 17 June 2021
  • 1.0.0 – 23 February 2021

Related Resources

Author Notes

MaterialsProjectData is meant as a lower-level interface, with a planned MaterialProperties[…] providing a more user-friendly access to properties.
Currently supports only the query() syntax. Should probably be extended to include get_data() and other goodies.
Should eventually handle both camelcase and underscore-separated properties (easy), as well as translation to/from the Wolfram Language name convention, along the lines of k_voight VoigtK (would require curation).
Returning results as Quantity objects would be useful (requires curation too).
Some Print statements should really be PrintTemporary, e.g. MaterialsProjectData["Li-O-*","material_id"]
Needs better error reporting, for instance, in the case of timeout:

MaterialsProjectData[…]:

Needs integration of the pymatgen.core.structure.Molecule API with Molecule[] and so on.
As of version 2.0 of MaterialsProjectData, extended to return dielectric and piezoelectric properties and, most importantly, the structure property.
As of version 2.0.1 of MaterialProjectData, updated to work properly with the most recent pymatgen package and uses the resource function PythonEvaluateWithDependencies to install pymatgen automatically (if it is not yet installed).

License Information