mp_api.client.mprester.MPRester

class mp_api.client.mprester.MPRester(api_key: str | None = None, endpoint: str = 'https://api.materialsproject.org/', notify_db_version: bool = False, include_user_agent: bool = True, monty_decode: bool = True, use_document_model: bool = True, session: Session = None, headers: dict = None, mute_progress_bars: bool = False)

Bases: object

Args: api_key (str): A String API key for accessing the MaterialsProject REST interface. Please obtain your API key at https://next-gen.materialsproject.org/api. If this is None, the code will check if there is a “MP_API_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 at “https://api.materialsproject.org”, but can be changed to other urls implementing a similar interface. notify_db_version (bool): If True, the current MP database version will be retrieved and logged locally in the ~/.mprester.log.yaml. If the database version changes, you will be notified. The current database version is also printed on instantiation. These local logs are not sent to materialsproject.org and are not associated with your API key, so be aware that a notification may not be presented if you run MPRester from multiple computing environments. include_user_agent (bool): If True, will include a user agent with the HTTP request including information on pymatgen and system version making the API request. This helps MP support pymatgen users, and is similar to what most web browsers send with each page request. Set to False to disable the user agent. monty_decode: Decode the data using monty into python objects use_document_model: If False, skip the creating the document model and return data as a dictionary. This can be simpler to work with but bypasses data validation and will not give auto-complete for available fields. session (Session): Session object to use. By default (None), the client will create one. headers (dict): Custom headers for localhost connections. mute_progress_bars (bool): Whether to mute progress bars.

__init__(api_key: str | None = None, endpoint: str = 'https://api.materialsproject.org/', notify_db_version: bool = False, include_user_agent: bool = True, monty_decode: bool = True, use_document_model: bool = True, session: Session = None, headers: dict = None, mute_progress_bars: bool = False)

Args: api_key (str): A String API key for accessing the MaterialsProject REST interface. Please obtain your API key at https://next-gen.materialsproject.org/api. If this is None, the code will check if there is a “MP_API_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 at “https://api.materialsproject.org”, but can be changed to other urls implementing a similar interface. notify_db_version (bool): If True, the current MP database version will be retrieved and logged locally in the ~/.mprester.log.yaml. If the database version changes, you will be notified. The current database version is also printed on instantiation. These local logs are not sent to materialsproject.org and are not associated with your API key, so be aware that a notification may not be presented if you run MPRester from multiple computing environments. include_user_agent (bool): If True, will include a user agent with the HTTP request including information on pymatgen and system version making the API request. This helps MP support pymatgen users, and is similar to what most web browsers send with each page request. Set to False to disable the user agent. monty_decode: Decode the data using monty into python objects use_document_model: If False, skip the creating the document model and return data as a dictionary. This can be simpler to work with but bypasses data validation and will not give auto-complete for available fields. session (Session): Session object to use. By default (None), the client will create one. headers (dict): Custom headers for localhost connections. mute_progress_bars (bool): Whether to mute progress bars.

Methods

__init__([api_key, endpoint, ...])	Args: api_key (str): A String API key for accessing the MaterialsProject REST interface.
find_structure(filename_or_structure[, ...])	Finds matching structures from the Materials Project database.
get_bandstructure_by_material_id(material_id)	Get the band structure pymatgen object associated with a Materials Project ID.
get_charge_density_from_material_id(material_id)	Get charge density data for a given Materials Project ID.
get_database_version()	The Materials Project database is periodically updated and has a database version associated with it.
get_dos_by_material_id(material_id)	Get the complete density of states pymatgen object associated with a Materials Project ID.
get_download_info(material_ids[, ...])	Get a list of URLs to retrieve raw VASP output files from the NoMaD repository :param material_ids: list of material identifiers (mp-id's) :type material_ids: list :param task_types: list of task types to include in download (see CalcType Enum class) :type task_types: list :param file_patterns: list of wildcard file names to include for each task :type file_patterns: list
get_emmet_version(endpoint)	Get the latest version emmet-core and emmet-api used in the current API service.
get_entries(chemsys_formula_mpids[, ...])	Get a list of ComputedEntries or ComputedStructureEntries corresponding to a chemical system or formula.
get_entries_in_chemsys(elements[, ...])	Helper method to get a list of ComputedEntries in a chemical system.
get_entry_by_material_id(material_id[, ...])	Get all ComputedEntry objects corresponding to a material_id.
get_ion_entries(pd[, ion_ref_data])	Retrieve IonEntry objects that can be used in the construction of Pourbaix Diagrams.
get_ion_reference_data()	Download aqueous ion reference data used in the construction of Pourbaix diagrams.
get_ion_reference_data_for_chemsys(chemsys)	Download aqueous ion reference data used in the construction of Pourbaix diagrams.
get_material_id_from_task_id(task_id)	Returns the current material_id from a given task_id.
get_material_id_references(material_id)	Returns all references for a material id.
get_material_ids(chemsys_formula)	Get all materials ids for a formula or chemsys.
get_materials_id_from_task_id(task_id)	This method is deprecated, please use get_material_id_from_task_id.
get_materials_id_references(material_id)	This method is deprecated, please use get_material_id_references.
get_materials_ids(chemsys_formula)	This method is deprecated, please use get_material_ids.
get_phonon_bandstructure_by_material_id(...)	Get phonon dispersion data corresponding to a material_id.
get_phonon_dos_by_material_id(material_id)	Get phonon density of states data corresponding to a material_id.
get_pourbaix_entries(chemsys[, ...])	A helper function to get all entries necessary to generate a Pourbaix diagram from the rest interface.
get_structure_by_material_id(material_id[, ...])	Get a Structure corresponding to a material_id.
get_structures(chemsys_formula[, final])	Get a list of Structures corresponding to a chemical system or formula.
get_task_ids_associated_with_material_id(...)	param material_id:
get_wulff_shape(material_id)	Constructs a Wulff shape for a material.
query(**kwargs)	The MPRester().query method has been replaced with the MPRester().summary.search method.

Attributes

eos
materials
similarity
tasks
xas
fermi
grain_boundary
substrates
surface_properties
phonon
elasticity
thermo
dielectric
piezoelectric
magnetism
summary
robocrys
synthesis
insertion_electrodes
charge_density
electronic_structure
electronic_structure_bandstructure
electronic_structure_dos
oxidation_states
provenance
bonds
alloys
absorption
chemenv
molecules
doi

get_task_ids_associated_with_material_id(material_id: str, calc_types: list[CalcType] | None = None) → list[str]

Parameters:

• material_id –

• calc_types – if specified, will restrict to certain task types, e.g. [CalcType.GGA_STATIC]

Returns:

get_structure_by_material_id(material_id: str, final: bool = True, conventional_unit_cell: bool = False) → Structure | list[Structure]

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 list of initial (pre-relaxation) structures. Defaults to True.

• conventional_unit_cell (bool) – Whether to get the standard conventional unit cell for the final or list of initial structures.

Returns:

Structure object or list of Structure objects.

get_database_version()

The Materials Project database is periodically updated and has a database version associated with it. When the database is updated, consolidated data (information about “a material”) may and does change, while calculation data about a specific calculation task remains unchanged and available for querying via its task_id.

The database version is set as a date in the format YYYY_MM_DD, where “_DD” may be optional. An additional numerical suffix might be added if multiple releases happen on the same day.

Returns: database version as a string

static get_emmet_version(endpoint)

Get the latest version emmet-core and emmet-api used in the current API service.

Returns: version as a string

get_material_id_from_task_id(task_id: str) → str | None

Returns the current material_id from a given task_id. The material_id should rarely change, and is usually chosen from among the smallest numerical id from the group of task_ids for that material. However, in some circumstances it might change, and this method is useful for finding the new material_id.

Parameters:

task_id (str) – A task id.

Returns:

material_id (MPID)

get_materials_id_from_task_id(task_id: str) → str | None

This method is deprecated, please use get_material_id_from_task_id.

get_material_id_references(material_id: str) → list[str]

Returns all references for a material id.

Parameters:

material_id (str) – A material id.

Returns:

List of BibTeX references ([str])

get_materials_id_references(material_id: str) → list[str]

This method is deprecated, please use get_material_id_references.

get_material_ids(chemsys_formula: str | list[str]) → list[MPID]

Get all materials ids for a formula or chemsys.

Parameters:

• chemsys_formula (str, List[str]) – A chemical system, list of chemical systems

• (e.g. (e.g., Fe2O3, Si*) –

• Li-Fe-O (e.g., Fe2O3, Si*) –

• Si-* (e.g., Fe2O3, Si*) –

• [Si-O (e.g., Fe2O3, Si*) –

• Li-Fe-P]) (e.g., Fe2O3, Si*) –

• formula (or single) –

Returns:

List of all materials ids ([MPID])

get_materials_ids(chemsys_formula: str | list[str]) → list[MPID]

This method is deprecated, please use get_material_ids.

get_structures(chemsys_formula: str | list[str], final=True) → list[Structure]

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

Parameters:

• chemsys_formula (str, List[str]) – A chemical system, list of chemical systems (e.g., Li-Fe-O, Si-, [Si-O, Li-Fe-P]), or single formula (e.g., Fe2O3, Si).

• final (bool) – Whether to get the final structure, or the list of initial (pre-relaxation) structures. Defaults to True.

Returns:

List of Structure objects. ([Structure])

find_structure(filename_or_structure: str | Structure, ltol: float = 0.2, stol: float = 0.3, angle_tol: float = 5.0, allow_multiple_results: bool = False) → list[str] | str

Finds matching structures from the Materials Project database.

Multiple results may be returned of “similar” structures based on distance using the pymatgen StructureMatcher algorithm, however only a single result should match with the same spacegroup, calculated to the default tolerances.

Parameters:

• filename_or_structure – filename or Structure object

• ltol – fractional length tolerance

• stol – site tolerance

• angle_tol – angle tolerance in degrees

• allow_multiple_results – changes return type for either

• material_ids (a single material_id or list of) –

Returns:

A matching material_id if one is found or list of results if allow_multiple_results is True

Raises:

MPRestError –

get_entries(chemsys_formula_mpids: str | list[str], compatible_only: bool = True, inc_structure: bool = None, property_data: list[str] = None, conventional_unit_cell: bool = False, additional_criteria: dict = None) → list[ComputedStructureEntry]

Get a list of ComputedEntries or ComputedStructureEntries corresponding to a chemical system or formula. This returns entries for all thermo types represented in the database. Each type corresponds to a different mixing scheme (i.e. GGA/GGA+U, GGA/GGA+U/R2SCAN, R2SCAN). By default the thermo_type of the entry is also returned.

Parameters:

• chemsys_formula_mpids (str, List[str]) – A chemical system, list of chemical systems (e.g., Li-Fe-O, Si-, [Si-O, Li-Fe-P]), formula, list of formulas (e.g., Fe2O3, Si, [SiO2, BiFeO3]), Materials Project ID, or list of Materials Project IDs (e.g., mp-22526, [mp-22526, mp-149]).

• compatible_only (bool) – Whether to return only “compatible” entries. Compatible entries are entries that have been processed using the MaterialsProject2020Compatibility class, which performs adjustments to allow mixing of GGA and GGA+U calculations for more accurate phase diagrams and reaction energies. This data is obtained from the core “thermo” API endpoint.

• inc_structure (str) – This is a deprecated argument. Previously, if None, entries returned were ComputedEntries. If inc_structure=”initial”, ComputedStructureEntries with initial structures were returned. Otherwise, ComputedStructureEntries with final structures were returned. This is no longer needed as all entries will contain structure data by default.

• property_data (list) – Specify additional properties to include in entry.data. If None, only default data is included. Should be a subset of input parameters in the ‘MPRester.thermo.available_fields’ list.

• conventional_unit_cell (bool) – Whether to get the standard conventional unit cell

• additional_criteria (dict) – Any additional criteria to pass. The keys and values should correspond to proper function inputs to MPRester.thermo.search. For instance, if you are only interested in entries on the convex hull, you could pass {“energy_above_hull”: (0.0, 0.0)} or {“is_stable”: True}.

Returns:

List ComputedStructureEntry objects.

get_pourbaix_entries(chemsys: str | list, solid_compat='MaterialsProject2020Compatibility', use_gibbs: Literal[300] | None = None)

A helper function to get all entries necessary to generate a Pourbaix diagram from the rest interface.

Parameters:

• chemsys (str or [str]) – Chemical system string comprising element symbols separated by dashes, e.g., “Li-Fe-O” or List of element symbols, e.g., [“Li”, “Fe”, “O”].

• solid_compat – Compatibility scheme used to pre-process solid DFT energies prior to applying aqueous energy adjustments. May be passed as a class (e.g. MaterialsProject2020Compatibility) or an instance (e.g., MaterialsProject2020Compatibility()). If None, solid DFT energies are used as-is. Default: MaterialsProject2020Compatibility

• use_gibbs – Set to 300 (for 300 Kelvin) to use a machine learning model to estimate solid free energy from DFT energy (see GibbsComputedStructureEntry). This can slightly improve the accuracy of the Pourbaix diagram in some cases. Default: None. Note that temperatures other than 300K are not permitted here, because MaterialsProjectAqueousCompatibility corrections, used in Pourbaix diagram construction, are calculated based on 300 K data.

get_ion_reference_data() → list[dict]

Download aqueous ion reference data used in the construction of Pourbaix diagrams.

Use this method to examine the ion reference data and to add additional ions if desired. The data returned from this method can be passed to get_ion_entries().

Data are retrieved from the Aqueous Ion Reference Data project hosted on MPContribs. Refer to that project and its associated documentation for more details about the format and meaning of the data.

Returns:

Among other data, each record contains 1) the experimental ion free energy, 2) the

formula of the reference solid for the ion, and 3) the experimental free energy of the reference solid. All energies are given in kJ/mol. An example is given below.

{‘identifier’: ‘Li[+]’, ‘formula’: ‘Li[+]’, ‘data’: {‘charge’: {‘display’: ‘1.0’, ‘value’: 1.0, ‘unit’: ‘’}, ‘ΔGᶠ’: {‘display’: ‘-293.71 kJ/mol’, ‘value’: -293.71, ‘unit’: ‘kJ/mol’}, ‘MajElements’: ‘Li’, ‘RefSolid’: ‘Li2O’, ‘ΔGᶠRefSolid’: {‘display’: ‘-561.2 kJ/mol’,

’value’: -561.2, ‘unit’: ‘kJ/mol’},

’reference’: ‘H. E. Barner and R. V. Scheuerman, Handbook of thermochemical data for compounds and aqueous species, Wiley, New York (1978)’}}

Return type:

[dict]

get_ion_reference_data_for_chemsys(chemsys: str | list) → list[dict]

Download aqueous ion reference data used in the construction of Pourbaix diagrams.

Use this method to examine the ion reference data and to add additional ions if desired. The data returned from this method can be passed to get_ion_entries().

Data are retrieved from the Aqueous Ion Reference Data project hosted on MPContribs. Refer to that project and its associated documentation for more details about the format and meaning of the data.

Parameters:

chemsys (str or [str]) – Chemical system string comprising element symbols separated by dashes, e.g., “Li-Fe-O” or List of element symbols, e.g., [“Li”, “Fe”, “O”].

Returns:

Among other data, each record contains 1) the experimental ion free energy, 2) the

formula of the reference solid for the ion, and 3) the experimental free energy of the reference solid. All energies are given in kJ/mol. An example is given below.

{‘identifier’: ‘Li[+]’, ‘formula’: ‘Li[+]’, ‘data’: {‘charge’: {‘display’: ‘1.0’, ‘value’: 1.0, ‘unit’: ‘’}, ‘ΔGᶠ’: {‘display’: ‘-293.71 kJ/mol’, ‘value’: -293.71, ‘unit’: ‘kJ/mol’}, ‘MajElements’: ‘Li’, ‘RefSolid’: ‘Li2O’, ‘ΔGᶠRefSolid’: {‘display’: ‘-561.2 kJ/mol’,

’value’: -561.2, ‘unit’: ‘kJ/mol’},

’reference’: ‘H. E. Barner and R. V. Scheuerman, Handbook of thermochemical data for compounds and aqueous species, Wiley, New York (1978)’}}

Return type:

[dict]

get_ion_entries(pd: PhaseDiagram, ion_ref_data: list[dict] | None = None) → list[IonEntry]

Retrieve IonEntry objects that can be used in the construction of Pourbaix Diagrams. The energies of the IonEntry are calculaterd from the solid energies in the provided Phase Diagram to be consistent with experimental free energies.

NOTE! This is an advanced method that assumes detailed understanding of how to construct computational Pourbaix Diagrams. If you just want to build a Pourbaix Diagram using default settings, use get_pourbaix_entries.

Parameters:

• pd – Solid phase diagram on which to construct IonEntry. Note that this Phase Diagram MUST include O and H in its chemical system. For example, to retrieve IonEntry for Ti, the phase diagram passed here should contain materials in the H-O-Ti chemical system. It is also assumed that solid energies have already been corrected with MaterialsProjectAqueousCompatibility, which is necessary for proper construction of Pourbaix diagrams.

• ion_ref_data – Aqueous ion reference data. If None (default), the data are downloaded from the Aqueous Ion Reference Data project hosted on MPContribs. To add a custom ionic species, first download data using get_ion_reference_data, then add or customize it with your additional data, and pass the customized list here.

Returns:

IonEntry are similar to PDEntry objects. Their energies

are free energies in eV.

Return type:

[IonEntry]

get_entry_by_material_id(material_id: str, compatible_only: bool = True, inc_structure: bool | None = None, property_data: list[str] | None = None, conventional_unit_cell: bool = False)

Get all ComputedEntry objects 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 MaterialsProject2020Compatibility class, which performs adjustments to allow mixing of GGA and GGA+U calculations for more accurate phase diagrams and reaction energies. This data is obtained from the core “thermo” API endpoint.

• inc_structure (str) – This is a deprecated argument. Previously, if None, entries returned were ComputedEntries. If inc_structure=”initial”, ComputedStructureEntries with initial structures were returned. Otherwise, ComputedStructureEntries with final structures were returned. This is no longer needed as all entries will contain structure data by default.

• property_data (list) – Specify additional properties to include in entry.data. If None, only default data is included. Should be a subset of input parameters in the ‘MPRester.thermo.available_fields’ list.

• conventional_unit_cell (bool) – Whether to get the standard conventional unit cell

Returns:

List of ComputedEntry or ComputedStructureEntry object.

get_entries_in_chemsys(elements: str | list[str], use_gibbs: int | None = None, compatible_only: bool = True, inc_structure: bool = None, property_data: list[str] = None, conventional_unit_cell: bool = False, additional_criteria=None)

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.

Note that by default this returns mixed GGA/GGA+U entries. For others, pass GGA/GGA+U/R2SCAN, or R2SCAN as thermo_types in additional_criteria.

Parameters:

• elements (str or [str]) – Chemical system string comprising element symbols separated by dashes, e.g., “Li-Fe-O” or List of element symbols, e.g., [“Li”, “Fe”, “O”].

• use_gibbs – If None (default), DFT energy is returned. If a number, return the free energy of formation estimated using a machine learning model (see GibbsComputedStructureEntry). The number is the temperature in Kelvin at which to estimate the free energy. Must be between 300 K and 2000 K.

• compatible_only (bool) – Whether to return only “compatible” entries. Compatible entries are entries that have been processed using the MaterialsProject2020Compatibility class, which performs adjustments to allow mixing of GGA and GGA+U calculations for more accurate phase diagrams and reaction energies. This data is obtained from the core “thermo” API endpoint.

• inc_structure (str) – This is a deprecated argument. Previously, if None, entries returned were ComputedEntries. If inc_structure=”initial”, ComputedStructureEntries with initial structures were returned. Otherwise, ComputedStructureEntries with final structures were returned. This is no longer needed as all entries will contain structure data by default.

• property_data (list) – Specify additional properties to include in entry.data. If None, only default data is included. Should be a subset of input parameters in the ‘MPRester.thermo.available_fields’ list.

• conventional_unit_cell (bool) – Whether to get the standard conventional unit cell

• additional_criteria (dict) – Any additional criteria to pass. The keys and values should correspond to proper function inputs to MPRester.thermo.search. For instance, if you are only interested in entries on the convex hull, you could pass {“energy_above_hull”: (0.0, 0.0)} or {“is_stable”: True}, or if you are only interested in entry data

Returns:

List of ComputedStructureEntries.

get_bandstructure_by_material_id(material_id: str, path_type: BSPathType = BSPathType.setyawan_curtarolo, line_mode=True)

Get the band structure pymatgen object associated with a Materials Project ID.

Parameters:

• material_id (str) – Materials Project ID for a material

• path_type (BSPathType) – k-point path selection convention

• line_mode (bool) – Whether to return data for a line-mode calculation

Returns:

BandStructure or BandStructureSymmLine object

Return type:

bandstructure (Union[BandStructure, BandStructureSymmLine])

get_dos_by_material_id(material_id: str)

Get the complete density of states pymatgen object associated with a Materials Project ID.

Parameters:

material_id (str) – Materials Project ID for a material

Returns:

CompleteDos object

Return type:

dos (CompleteDos)

get_phonon_dos_by_material_id(material_id: str)

Get phonon density of states data corresponding to a material_id.

Parameters:

material_id (str) – Materials Project material_id.

Returns:

A phonon DOS object.

Return type:

CompletePhononDos

get_phonon_bandstructure_by_material_id(material_id: str)

Get phonon dispersion data corresponding to a material_id.

Parameters:

material_id (str) – Materials Project material_id.

Returns:

phonon band structure.

Return type:

PhononBandStructureSymmLine

get_wulff_shape(material_id: str)

Constructs a Wulff shape for a material.

Parameters:

material_id (str) – Materials Project material_id, e.g. ‘mp-123’.

Returns:

pymatgen.analysis.wulff.WulffShape

get_charge_density_from_material_id(material_id: str, inc_task_doc: bool = False) → Chgcar | None

Get charge density data for a given Materials Project ID.

Parameters:

• material_id (str) – Material Project ID

• inc_task_doc (bool) – Whether to include the task document in the returned data.

Returns:

Pymatgen Chgcar object.

Return type:

chgcar

get_download_info(material_ids, calc_types=None, file_patterns=None)

Get a list of URLs to retrieve raw VASP output files from the NoMaD repository :param material_ids: list of material identifiers (mp-id’s) :type material_ids: list :param task_types: list of task types to include in download (see CalcType Enum class) :type task_types: list :param file_patterns: list of wildcard file names to include for each task :type file_patterns: list

Returns:

a tuple of 1) a dictionary mapping material_ids to task_ids and calc_types, and 2) a list of URLs to download zip archives from NoMaD repository. Each zip archive will contain a manifest.json with metadata info, e.g. the task/external_ids that belong to a directory.

query(**kwargs)

The MPRester().query method has been replaced with the MPRester().summary.search method. Note this method also no longer supports direct MongoDB-type queries. For more information, please see the new documentation.