pymatgen.ext.matproj module

exception MPRestError[source]

Bases: Exception

Exception class for MPRestAdaptor. Raised when the query has problems, e.g., bad query format.

class MPRester(api_key=None, endpoint='https://www.materialsproject.org/rest/v2')[source]

Bases: object

A class to conveniently interface with the Materials Project REST interface. The recommended way to use MPRester is with the “with” context manager to ensure that sessions are properly closed after usage:

with MPRester("API_KEY") as m:
    do_something

MPRester uses the “requests” package, which provides for HTTP connection pooling. All connections are made via https for security.

Note

The Materials Project recently switched to using string ids with a “mp-” prefix for greater flexibility going forward. The MPRester should still work as intended if you provide the proper string ids.

Parameters:
  • api_key (str) – A String API key for accessing the MaterialsProject REST interface. Please obtain your API key at https://www.materialsproject.org/dashboard. If this is None, the code will check if there is a “PMG_MAPI_KEY” setting. If so, it will use that environment variable. This makes easier for heavy users to simply add this environment variable to their setups and MPRester can then be called without any arguments.
  • endpoint (str) – Url of endpoint to access the MaterialsProject REST interface. Defaults to the standard Materials Project REST address, but can be changed to other urls implementing a similar interface.
delete_snl(snl_ids)[source]

Delete earlier submitted SNLs.

Note

As of now, this MP REST feature is open only to a select group of users. Opening up submissions to all users is being planned for the future.

Parameters:snl_ids – List of SNL ids.
Raises:MPRestError
find_structure(filename_or_structure)[source]

Finds matching structures on the Materials Project site.

Parameters:filename_or_structure – filename or Structure object
Returns:A list of matching structures.
Raises:MPRestError
get_all_substrates()[source]

Gets the list of all possible substrates considered in the Materials Project substrate database

Returns:list of material_ids corresponding to possible substrates
get_bandstructure_by_material_id(material_id)[source]

Get a BandStructure corresponding to a material_id.

Parameters:material_id (str) – Materials Project material_id (an int).
Returns:A BandStructure object.
get_data(chemsys_formula_id, data_type='vasp', prop='')[source]

Flexible method to get any data using the Materials Project REST interface. Generally used by other methods for more specific queries.

Format of REST return is always a list of dict (regardless of the number of pieces of data returned. The general format is as follows:

[{“material_id”: material_id, “property_name” : value}, …]

Parameters:
  • chemsys_formula_id (str) – A chemical system (e.g., Li-Fe-O), or formula (e.g., Fe2O3) or materials_id (e.g., mp-1234).
  • data_type (str) – Type of data to return. Currently can either be “vasp” or “exp”.
  • prop (str) – Property to be obtained. Should be one of the MPRester.supported_task_properties. Leave as empty string for a general list of useful properties.
get_dos_by_material_id(material_id)[source]

Get a Dos corresponding to a material_id.

Parameters:material_id (str) – Materials Project material_id (a string, e.g., mp-1234).
Returns:A Dos object.
get_entries(chemsys_formula_id_criteria, compatible_only=True, inc_structure=None, property_data=None)[source]

Get a list of ComputedEntries or ComputedStructureEntries corresponding to a chemical system, formula, or materials_id or full criteria.

Parameters:
  • chemsys_formula_id_criteria (str/dict) – A chemical system (e.g., Li-Fe-O), or formula (e.g., Fe2O3) or materials_id (e.g., mp-1234) or full Mongo-style dict criteria.
  • compatible_only (bool) – Whether to return only “compatible” entries. Compatible entries are entries that have been processed using the MaterialsProjectCompatibility class, which performs adjustments to allow mixing of GGA and GGA+U calculations for more accurate phase diagrams and reaction energies.
  • inc_structure (str) – If None, entries returned are ComputedEntries. If inc_structure=”final”, ComputedStructureEntries with final structures are returned. Otherwise, ComputedStructureEntries with initial structures are returned.
  • property_data (list) – Specify additional properties to include in entry.data. If None, no data. Should be a subset of supported_properties.
Returns:

List of ComputedEntry or ComputedStructureEntry objects.

get_entries_in_chemsys(elements, compatible_only=True, inc_structure=None, property_data=None)[source]

Helper method to get a list of ComputedEntries in a chemical system. For example, elements = [“Li”, “Fe”, “O”] will return a list of all entries in the Li-Fe-O chemical system, i.e., all LixOy, FexOy, LixFey, LixFeyOz, Li, Fe and O phases. Extremely useful for creating phase diagrams of entire chemical systems.

Parameters:
  • elements ([str]) – List of element symbols, e.g., [“Li”, “Fe”, “O”].
  • compatible_only (bool) – Whether to return only “compatible” entries. Compatible entries are entries that have been processed using the MaterialsProjectCompatibility class, which performs adjustments to allow mixing of GGA and GGA+U calculations for more accurate phase diagrams and reaction energies.
  • inc_structure (str) – If None, entries returned are ComputedEntries. If inc_structure=”final”, ComputedStructureEntries with final structures are returned. Otherwise, ComputedStructureEntries with initial structures are returned.
  • property_data (list) – Specify additional properties to include in entry.data. If None, no data. Should be a subset of supported_properties.
Returns:

List of ComputedEntries.

get_entry_by_material_id(material_id, compatible_only=True, inc_structure=None, property_data=None)[source]

Get a ComputedEntry corresponding to a material_id.

Parameters:
  • material_id (str) – Materials Project material_id (a string, e.g., mp-1234).
  • compatible_only (bool) – Whether to return only “compatible” entries. Compatible entries are entries that have been processed using the MaterialsProjectCompatibility class, which performs adjustments to allow mixing of GGA and GGA+U calculations for more accurate phase diagrams and reaction energies.
  • inc_structure (str) – If None, entries returned are ComputedEntries. If inc_structure=”final”, ComputedStructureEntries with final structures are returned. Otherwise, ComputedStructureEntries with initial structures are returned.
  • property_data (list) – Specify additional properties to include in entry.data. If None, no data. Should be a subset of supported_properties.
Returns:

ComputedEntry or ComputedStructureEntry object.

get_exp_entry(formula)[source]

Returns an ExpEntry object, which is the experimental equivalent of a ComputedEntry and can be used for analyses using experimental data.

Parameters:formula (str) – A formula to search for.
Returns:An ExpEntry object.
get_exp_thermo_data(formula)[source]

Get a list of ThermoData objects associated with a formula using the Materials Project REST interface.

Parameters:formula (str) – A formula to search for.
Returns:List of ThermoData objects.
get_materials_id_from_task_id(task_id)[source]

Returns a new MP materials id from a task id (which can be equivalent to an old materials id)

Parameters:task_id (str) – A task id.
Returns:materials_id (str)
get_materials_id_references(material_id)[source]

Returns all references for a materials id.

Parameters:material_id (str) – A material id.
Returns:BibTeX (str)
get_reaction(reactants, products)[source]

Gets a reaction from the Materials Project.

Parameters:
  • reactants ([str]) – List of formulas
  • products ([str]) – List of formulas
Returns:

rxn

get_stability(entries)[source]

Returns the stability of all entries.

get_structure_by_material_id(material_id, final=True)[source]

Get a Structure corresponding to a material_id.

Parameters:
  • material_id (str) – Materials Project material_id (a string, e.g., mp-1234).
  • final (bool) – Whether to get the final structure, or the initial (pre-relaxation) structure. Defaults to True.
Returns:

Structure object.

get_structures(chemsys_formula_id, final=True)[source]

Get a list of Structures corresponding to a chemical system, formula, or materials_id.

Parameters:
  • chemsys_formula_id (str) – A chemical system (e.g., Li-Fe-O), or formula (e.g., Fe2O3) or materials_id (e.g., mp-1234).
  • final (bool) – Whether to get the final structure, or the initial (pre-relaxation) structure. Defaults to True.
Returns:

List of Structure objects.

get_substrates(material_id, number=50, orient=None)[source]

Get a substrate list for a material id. The list is in order of increasing elastic energy if a elastic tensor is available for the material_id. Otherwise the list is in order of increasing matching area.

Parameters:
  • material_id (str) – Materials Project material_id, e.g. ‘mp-123’.
  • orient (list) – substrate orientation to look for
  • number (int) – number of substrates to return; n=0 returns all available matches
Returns:

list of dicts with substrate matches

get_task_data(chemsys_formula_id, prop='')[source]

Flexible method to get any data using the Materials Project REST interface. Generally used by other methods for more specific queries. Unlike the :func:`get_data`_, this method queries the task collection for specific run information.

Format of REST return is always a list of dict (regardless of the number of pieces of data returned. The general format is as follows:

[{“material_id”: material_id, “property_name” : value}, …]

Parameters:
  • chemsys_formula_id (str) – A chemical system (e.g., Li-Fe-O), or formula (e.g., Fe2O3) or materials_id (e.g., mp-1234).
  • prop (str) – Property to be obtained. Should be one of the MPRester.supported_properties. Leave as empty string for a general list of useful properties.
static parse_criteria(criteria_string)[source]

Parses a powerful and simple string criteria and generates a proper mongo syntax criteria.

Parameters:criteria_string (str) –

A string representing a search criteria. Also supports wild cards. E.g., something like “*2O” gets converted to {‘pretty_formula’: {‘$in’: [u’B2O’, u’Xe2O’, u”Li2O”, …]}}

Other syntax examples:
mp-1234: Interpreted as a Materials ID. Fe2O3 or *2O3: Interpreted as reduced formulas. Li-Fe-O or *-Fe-O: Interpreted as chemical systems.

You can mix and match with spaces, which are interpreted as “OR”. E.g., “mp-1234 FeO” means query for all compounds with reduced formula FeO or with materials_id mp-1234.

Returns:A mongo query dict.
query(criteria, properties, mp_decode=True)[source]

Performs an advanced query, which is a Mongo-like syntax for directly querying the Materials Project database via the query rest interface. Please refer to the Materials Project REST wiki https://materialsproject.org/wiki/index.php/The_Materials_API#query on the query language and supported criteria and properties. Essentially, any supported properties within MPRester should be supported in query.

Query allows an advanced developer to perform queries which are otherwise too cumbersome to perform using the standard convenience methods.

It is highly recommended that you consult the Materials API documentation at http://bit.ly/materialsapi, which provides a comprehensive explanation of the document schema used in the Materials Project and how best to query for the relevant information you need.

Parameters:
  • criteria (str/dict) –

    Criteria of the query as a string or mongo-style dict.

    If string, it supports a powerful but simple string criteria. E.g., “Fe2O3” means search for materials with reduced_formula Fe2O3. Wild cards are also supported. E.g., “*2O” means get all materials whose formula can be formed as *2O, e.g., Li2O, K2O, etc.

    Other syntax examples: mp-1234: Interpreted as a Materials ID. Fe2O3 or *2O3: Interpreted as reduced formulas. Li-Fe-O or *-Fe-O: Interpreted as chemical systems.

    You can mix and match with spaces, which are interpreted as “OR”. E.g. “mp-1234 FeO” means query for all compounds with reduced formula FeO or with materials_id mp-1234.

    Using a full dict syntax, even more powerful queries can be constructed. For example, {“elements”:{“$in”:[“Li”, “Na”, “K”], “$all”: [“O”]}, “nelements”:2} selects all Li, Na and K oxides. {“band_gap”: {“$gt”: 1}} selects all materials with band gaps greater than 1 eV.

  • properties (list) – Properties to request for as a list. For example, [“formula”, “formation_energy_per_atom”] returns the formula and formation energy per atom.
  • mp_decode (bool) – Whether to do a decoding to a Pymatgen object where possible. In some cases, it might be useful to just get the raw python dict, i.e., set to False.
Returns:

List of results. E.g., [{u’formula’: {u’O’: 1, u’Li’: 2.0}}, {u’formula’: {u’Na’: 2.0, u’O’: 2.0}}, {u’formula’: {u’K’: 1, u’O’: 3.0}}, …]

query_snl(criteria)[source]

Query for submitted SNLs.

Note

As of now, this MP REST feature is open only to a select group of users. Opening up submissions to all users is being planned for the future.

Parameters:criteria (dict) – Query criteria.
Returns:A dict, with a list of submitted SNLs in the “response” key.
Raises:MPRestError
submit_snl(snl)[source]

Submits a list of StructureNL to the Materials Project site.

Note

As of now, this MP REST feature is open only to a select group of users. Opening up submissions to all users is being planned for the future.

Parameters:
  • snl (StructureNL/[StructureNL]) – A single StructureNL, or a list
  • StructureNL objects (of) –
Returns:

A list of inserted submission ids.

Raises:

MPRestError

submit_structures(structures, authors, projects=None, references='', remarks=None, data=None, histories=None, created_at=None)[source]

Submits a list of structures to the Materials Project as SNL files. The argument list mirrors the arguments for the StructureNL object, except that a list of structures with the same metadata is used as an input.

Note

As of now, this MP REST feature is open only to a select group of users. Opening up submissions to all users is being planned for the future.

Parameters:
  • structures – A list of Structure objects
  • authors (list) – List of {“name”:’‘, “email”:’‘} dicts, list of Strings as ‘John Doe <johndoe@gmail.com>’, or a single String with commas separating authors
  • projects ([str]) – List of Strings [‘Project A’, ‘Project B’]. This applies to all structures.
  • references (str) – A String in BibTeX format. Again, this applies to all structures.
  • remarks ([str]) – List of Strings [‘Remark A’, ‘Remark B’]
  • data ([dict]) – A list of free form dict. Namespaced at the root level with an underscore, e.g. {“_materialsproject”:<custom data>}. The length of data should be the same as the list of structures if not None.
  • histories – List of list of dicts - [[{‘name’:’‘, ‘url’:’‘, ‘description’:{}}], …] The length of histories should be the same as the list of structures if not None.
  • created_at (datetime) – A datetime object
Returns:

A list of inserted submission ids.

submit_vasp_directory(rootdir, authors, projects=None, references='', remarks=None, master_data=None, master_history=None, created_at=None, ncpus=None)[source]

Assimilates all vasp run directories beneath a particular directory using BorgQueen to obtain structures, and then submits thhem to the Materials Project as SNL files. VASP related meta data like initial structure and final energies are automatically incorporated.

Note

As of now, this MP REST feature is open only to a select group of users. Opening up submissions to all users is being planned for the future.

Parameters:
  • rootdir (str) – Rootdir to start assimilating VASP runs from.
  • authorsList of {“name”:’‘, “email”:’‘} dicts, list of Strings as ‘John Doe <johndoe@gmail.com>’, or a single String with commas separating authors. The same list of authors should apply to all runs.
  • projects ([str]) – List of Strings [‘Project A’, ‘Project B’]. This applies to all structures.
  • references (str) – A String in BibTeX format. Again, this applies to all structures.
  • remarks ([str]) – List of Strings [‘Remark A’, ‘Remark B’]
  • master_data (dict) – A free form dict. Namespaced at the root level with an underscore, e.g. {“_materialsproject”:<custom data>}. This data is added to all structures detected in the directory, in addition to other vasp data on a per structure basis.
  • master_history – A master history to be added to all entries.
  • created_at (datetime) – A datetime object
  • ncpus (int) – Number of cpus to use in using BorgQueen to assimilate. Defaults to None, which means serial.
supported_properties = ('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', 'task_ids', 'band_gap', 'density', 'icsd_id', 'icsd_ids', 'cif', 'total_magnetization', 'material_id', 'oxide_type', 'tags', 'elasticity')
supported_task_properties = ('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')