mp_api.client.routes.materials.materials.MaterialsRester

class mp_api.client.routes.materials.materials.MaterialsRester(**kwargs)[source]

Bases: CoreRester

Ensure that sub resters are unset on re-init.

__init__(**kwargs)

Ensure that sub resters are unset on re-init.

Methods

__init__(**kwargs)

Ensure that sub resters are unset on re-init.

count([criteria])

Return a count of total documents.

find_structure(filename_or_structure[, ...])

Finds matching structures from the Materials Project database.

get_blessed_entries([run_type, ...])

Get blessed calculation entries for a given material and run type.

get_data_by_id(document_id[, fields])

get_structure_by_material_id(material_id[, ...])

Get a structure for a given Materials Project ID.

search([material_ids, chemsys, ...])

Query core material docs using a variety of search criteria.

Attributes

available_fields

primary_key

s3_client

session

suffix

document_model

alias of MaterialsDoc

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

Get a structure for a given Materials Project ID.

Parameters:

  • material_id (str) – Materials project ID

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

Returns:

Pymatgen structure object or list of

pymatgen structure objects.

Return type:

structure (Union[Structure, List[Structure]])

search(material_ids: str | list[str] | None = None, chemsys: str | list[str] | None = None, crystal_system: CrystalSystem | None = None, density: tuple[float, float] | None = None, deprecated: bool | None = False, elements: list[str] | None = None, exclude_elements: list[str] | None = None, formula: str | list[str] | None = None, num_elements: tuple[int, int] | None = None, num_sites: tuple[int, int] | None = None, spacegroup_number: int | None = None, spacegroup_symbol: str | None = None, task_ids: list[str] | None = None, volume: tuple[float, float] | None = None, num_chunks: int | None = None, chunk_size: int = 1000, all_fields: bool = True, fields: list[str] | None = None) → list[MaterialsDoc] | list[dict][source]

Query core material docs using a variety of search criteria.

Parameters:

  • material_ids (str, List[str]) – A single Material ID string or list of strings (e.g., mp-149, [mp-149, mp-13]).

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

  • 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.

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

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

  • 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]).

  • 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.

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

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

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

  • volume (Tuple[float,float]) – Minimum and maximum volume 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 MaterialsCoreDoc to return data for. Default is material_id, last_updated, and formula_pretty if all_fields is False.

Returns:

([MaterialsDoc], [dict]) List of material documents or dictionaries.

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

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_blessed_entries(run_type: str | RunType = RunType.r2SCAN, material_ids: list[str] | None = None, uncorrected_energy: tuple[float | None, float | None] | float | None = None, num_chunks: int | None = None, chunk_size: int = 1000) → list[dict[str, str | dict | ComputedStructureEntry]][source]

Get blessed calculation entries for a given material and run type.

Parameters:

  • run_type (str or RunType) – Calculation run type (e.g. GGA, GGA+U, r2SCAN, PBESol)

  • material_ids (list[str]) – List of material ID values

  • uncorrected_energy (tuple[Optional[float], Optional[float]] | float) – Tuple of minimum and maximum uncorrected DFT energy in eV/atom. Note that if a single value is passed, it will be used as the minimum and maximum.

  • 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.

Returns:

{

“material_id”: MPID, “blessed_entry”: ComputedStructureEntry

}

Return type:

list of dict, of the form

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

Return a count of total documents.

Parameters:

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

Returns:

Count of total results, or string indicating error

Return type:

(int | str)