mp_api.client.routes.materials.summary.SummaryRester

class mp_api.client.routes.materials.summary.SummaryRester(api_key: str | None = None, endpoint: str = 'https://api.materialsproject.org/', include_user_agent: bool = True, session: requests.Session | None = None, s3_resource: Any | None = None, debug: bool = False, monty_decode: bool = True, use_document_model: bool = True, timeout: int = 20, headers: dict = None, mute_progress_bars: bool = False)[source]

Bases: BaseRester[SummaryDoc]

Args: 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 at “https://api.materialsproject.org”, but can be changed to other urls implementing a similar interface. 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. session: requests Session object with which to connect to the API, for advanced usage only. debug: if True, print the URL for every request 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. timeout: Time in seconds to wait until a request timeout error is thrown headers (dict): Custom headers for localhost connections.

__init__(api_key: str | None = None, endpoint: str = 'https://api.materialsproject.org/', include_user_agent: bool = True, session: requests.Session | None = None, s3_resource: Any | None = None, debug: bool = False, monty_decode: bool = True, use_document_model: bool = True, timeout: int = 20, 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://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 at “https://api.materialsproject.org”, but can be changed to other urls implementing a similar interface. 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. session: requests Session object with which to connect to the API, for advanced usage only. debug: if True, print the URL for every request 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. timeout: Time in seconds to wait until a request timeout error is thrown headers (dict): Custom headers for localhost connections.

Methods

__init__([api_key, endpoint, ...])

Args: api_key (str): A String API key for accessing the MaterialsProject REST interface.

count([criteria])

Return a count of total documents.

get_data_by_id(document_id[, fields])

Query the endpoint for a single document.

search([band_gap, chemsys, crystal_system, ...])

Query core data using a variety of search criteria.

search_summary_docs(*args, **kwargs)

Deprecated.

Attributes

available_fields

primary_key

s3_resource

session

suffix

supports_versions

document_model

alias of SummaryDoc

search_summary_docs(*args, **kwargs)[source]

Deprecated.

search(band_gap: tuple[float, float] | None = None, chemsys: str | list[str] | None = None, crystal_system: CrystalSystem | None = None, density: tuple[float, float] | None = None, deprecated: bool | None = None, e_electronic: tuple[float, float] | None = None, e_ionic: tuple[float, float] | None = None, e_total: tuple[float, float] | None = None, efermi: tuple[float, float] | None = None, elastic_anisotropy: tuple[float, float] | None = None, elements: list[str] | None = None, energy_above_hull: tuple[float, float] | None = None, equilibrium_reaction_energy: tuple[float, float] | None = None, exclude_elements: list[str] | None = None, formation_energy: tuple[float, float] | None = None, formula: str | list[str] | None = None, g_reuss: tuple[float, float] | None = None, g_voigt: tuple[float, float] | None = None, g_vrh: tuple[float, float] | None = None, has_props: list[HasProps] | None = None, has_reconstructed: bool | None = None, is_gap_direct: bool | None = None, is_metal: bool | None = None, is_stable: bool | None = None, k_reuss: tuple[float, float] | None = None, k_voigt: tuple[float, float] | None = None, k_vrh: tuple[float, float] | None = None, magnetic_ordering: Ordering | None = None, material_ids: list[MPID] | None = None, n: tuple[float, float] | None = None, num_elements: tuple[int, int] | None = None, num_sites: tuple[int, int] | None = None, num_magnetic_sites: tuple[int, int] | None = None, num_unique_magnetic_sites: tuple[int, int] | None = None, piezoelectric_modulus: tuple[float, float] | None = None, poisson_ratio: tuple[float, float] | None = None, possible_species: list[str] | None = None, shape_factor: tuple[float, float] | None = None, spacegroup_number: int | None = None, spacegroup_symbol: str | None = None, surface_energy_anisotropy: tuple[float, float] | None = None, theoretical: bool | None = None, total_energy: tuple[float, float] | None = None, total_magnetization: tuple[float, float] | None = None, total_magnetization_normalized_formula_units: tuple[float, float] | None = None, total_magnetization_normalized_vol: tuple[float, float] | None = None, uncorrected_energy: tuple[float, float] | None = None, volume: tuple[float, float] | None = None, weighted_surface_energy: tuple[float, float] | None = None, weighted_work_function: tuple[float, float] | None = None, num_chunks: int | None = None, chunk_size: int = 1000, all_fields: bool = True, fields: list[str] | None = None)[source]

Query core data using a variety of search criteria.

Parameters:

  • band_gap (Tuple[float,float]) – Minimum and maximum band gap in eV to consider.

  • chemsys (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).

  • crystal_system (CrystalSystem) – Crystal system of material.

  • density (Tuple[float,float]) – Minimum and maximum density to consider.

  • deprecated (bool) – Whether the material is tagged as deprecated.

  • e_electronic (Tuple[float,float]) – Minimum and maximum electronic dielectric constant to consider.

  • e_ionic (Tuple[float,float]) – Minimum and maximum ionic dielectric constant to consider.

  • e_total (Tuple[float,float]) – Minimum and maximum total dielectric constant to consider.

  • efermi (Tuple[float,float]) – Minimum and maximum fermi energy in eV to consider.

  • elastic_anisotropy (Tuple[float,float]) – Minimum and maximum value to consider for the elastic anisotropy.

  • elements (List[str]) – A list of elements.

  • energy_above_hull (Tuple[int,int]) – Minimum and maximum energy above the hull in eV/atom to consider.

  • equilibrium_reaction_energy (Tuple[float,float]) – Minimum and maximum equilibrium reaction energy in eV/atom to consider.

  • exclude_elements (List(str)) – List of elements to exclude.

  • formation_energy (Tuple[int,int]) – Minimum and maximum formation energy in eV/atom to consider.

  • formula (str, List[str]) – A formula including anonymized formula or wild cards (e.g., Fe2O3, ABO3, Si*). A list of chemical formulas can also be passed (e.g., [Fe2O3, ABO3]).

  • g_reuss (Tuple[float,float]) – Minimum and maximum value in GPa to consider for the Reuss average of the shear modulus.

  • g_voigt (Tuple[float,float]) – Minimum and maximum value in GPa to consider for the Voigt average of the shear modulus.

  • g_vrh (Tuple[float,float]) – Minimum and maximum value in GPa to consider for the Voigt-Reuss-Hill average of the shear modulus.

  • has_props – (List[HasProps]): The calculated properties available for the material.

  • has_reconstructed (bool) – Whether the entry has any reconstructed surfaces.

  • is_gap_direct (bool) – Whether the material has a direct band gap.

  • is_metal (bool) – Whether the material is considered a metal.

  • is_stable (bool) – Whether the material lies on the convex energy hull.

  • k_reuss (Tuple[float,float]) – Minimum and maximum value in GPa to consider for the Reuss average of the bulk modulus.

  • k_voigt (Tuple[float,float]) – Minimum and maximum value in GPa to consider for the Voigt average of the bulk modulus.

  • k_vrh (Tuple[float,float]) – Minimum and maximum value in GPa to consider for the Voigt-Reuss-Hill average of the bulk modulus.

  • magnetic_ordering (Ordering) – Magnetic ordering of the material.

  • material_ids (List[MPID]) – List of Materials Project IDs to return data for.

  • n (Tuple[float,float]) – Minimum and maximum refractive index to consider.

  • num_elements (Tuple[int,int]) – Minimum and maximum number of elements to consider.

  • num_sites (Tuple[int,int]) – Minimum and maximum number of sites to consider.

  • num_magnetic_sites (Tuple[int,int]) – Minimum and maximum number of magnetic sites to consider.

  • num_unique_magnetic_sites (Tuple[int,int]) – Minimum and maximum number of unique magnetic sites to consider.

  • piezoelectric_modulus (Tuple[float,float]) – Minimum and maximum piezoelectric modulus to consider.

  • poisson_ratio (Tuple[float,float]) – Minimum and maximum value to consider for Poisson’s ratio.

  • possible_species (List(str)) – List of element symbols appended with oxidation states. (e.g. Cr2+,O2-)

  • shape_factor (Tuple[float,float]) – Minimum and maximum shape factor values to consider.

  • spacegroup_number (int) – Space group number of material.

  • spacegroup_symbol (str) – Space group symbol of the material in international short symbol notation.

  • surface_energy_anisotropy (Tuple[float,float]) – Minimum and maximum surface energy anisotropy values to consider.

  • theoretical – (bool): Whether the material is theoretical.

  • total_energy (Tuple[int,int]) – Minimum and maximum corrected total energy in eV/atom to consider.

  • total_magnetization (Tuple[float,float]) – Minimum and maximum total magnetization values to consider.

  • total_magnetization_normalized_formula_units (Tuple[float,float]) – Minimum and maximum total magnetization values normalized by formula units to consider.

  • total_magnetization_normalized_vol (Tuple[float,float]) – Minimum and maximum total magnetization values normalized by volume to consider.

  • uncorrected_energy (Tuple[int,int]) – Minimum and maximum uncorrected total energy in eV/atom to consider.

  • volume (Tuple[float,float]) – Minimum and maximum volume to consider.

  • weighted_surface_energy (Tuple[float,float]) – Minimum and maximum weighted surface energy in J/m² to consider.

  • weighted_work_function (Tuple[float,float]) – Minimum and maximum weighted work function in eV to consider.

  • num_chunks (int) – Maximum number of chunks of data to yield. None will yield all possible.

  • chunk_size (int) – Number of data entries per chunk.

  • all_fields (bool) – Whether to return all fields in the document. Defaults to True.

  • fields (List[str]) – List of fields in SearchDoc to return data for. Default is material_id if all_fields is False.

Returns:

([SummaryDoc]) List of SummaryDoc documents

count(criteria: dict | None = None) → int | str

Return a count of total documents.

Parameters:

criteria (dict | None) – As in .query(). Defaults to None

Returns:

Count of total results, or string indicating error

Return type:

(int | str)

get_data_by_id(document_id: str, fields: list[str] | None = None) → T

Query the endpoint for a single document.

Parameters:

  • document_id – the unique key for this kind of document, typically a task_id

  • fields – list of fields to return, by default will return all fields

Returns:

A single document.