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.

available_db_versions()

Database versions available for this collection's full dataset on S3.

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

delta_backed

delta_catalog

The DeltaCatalog used for delta-backed queries, created on first use.

primary_key

query_builder

use delta_catalog.

s3_client

session

suffix

document_model

alias of MaterialsDoc

get_structure_by_material_id(material_id: str, final: bool = True) → Structure | list[Structure] | None[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 (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, db_version: 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.

  • db_version (str | None) – Database version to download when no filters are given (full dataset), e.g. “2026.04.13” or “latest”. Defaults to the rester’s version. See available_db_versions().

Returns:

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

find_structure(filename_or_structure: str | Path | Structure, ltol=0.2, stol=0.3, angle_tol=5.0, allow_multiple_results: bool | int = 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 as a str or Path, or a Structure object

  • ltol – fractional length tolerance

  • stol – site tolerance

  • angle_tol – angle tolerance in degrees

  • allow_multiple_results (bool or int) – changes return type for either a single material_id or list of material_ids. If a bool, returns either all matches (True) or one match at most (False). If an int, returns that many matches at most.

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, Any]][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[float | None, float | None] | 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

available_db_versions() → list[str]

Database versions available for this collection’s full dataset on S3.

Read from the DeltaTable’s log, no data is downloaded. Any of these can be pinned with MPRester(db_version=…) to download that version of the dataset.

Returns:

sorted database versions, e.g. [“2026.04.13”, “2026.09.28”]

Return type:

list of str

Raises:

MPRestError – if this collection isn’t delta-backed, or its dataset isn’t partitioned by database version.

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

Return a count of total documents.

Parameters:

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

Returns:

Count of total results

Return type:

int

property delta_catalog: DeltaCatalog

The DeltaCatalog used for delta-backed queries, created on first use.

property query_builder: QueryBuilderWithCache

use delta_catalog.

Type:

Deprecated