mp_api.client.routes.molecules.molecules.MoleculeRester

class mp_api.client.routes.molecules.molecules.MoleculeRester(**kwargs)

Bases: BaseMoleculeRester

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_molecule(filename_or_molecule[, ...])	Finds matching molecules from the Materials Project molecules database (MPcules).
get_data_by_id(document_id[, fields])
get_molecule_by_mpculeid(mpcule_id[, final])	Get a molecule object for a given Materials Project molecules ID (MPculeID).
search([charge, spin_multiplicity, ...])	Query molecule docs using a variety of search criteria.

Attributes

available_fields
primary_key
s3_client
session
suffix

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)

document_model

alias of MoleculeDoc

find_molecule(filename_or_molecule: str | Molecule, charge: int | None = None, spin_multiplicity: int | None = None, tolerance: float = 0.01, allow_multiple_results: bool = False) → list[str] | str

Finds matching molecules from the Materials Project molecules database (MPcules).

Multiple results may be returned of “similar” molecules based on distance using the pymatgen MoleculeMatcher algorithm.

Parameters:

• filename_or_molecule – filename or Molecule object

• charge – Molecule charge. Default is None, meaning that the charge will not be used to restrict the output.

• spin_multiplicity – Molecule’s spin multiplicity. Default is None, meaning that the output will not be restricted by spin multiplicity.

• tolerance – RMSD difference threshold for MoleculeMatcher

• allow_multiple_results – changes return type for either

• mpcule_ids (a single mpcule_id or list of)

Returns:

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

Raises:

MPRestError –

get_molecule_by_mpculeid(mpcule_id: str, final: bool = True) → Molecule | list[Molecule]

Get a molecule object for a given Materials Project molecules ID (MPculeID).

Parameters:

• mpcule_id (str) – Materials project molecule ID

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

Returns:

Pymatgen Molecule object or list of

pymatgen Molecule objects.

Return type:

molecule (Union[Molecule, List[Molecule]])

search(charge: tuple[int, int] | None = None, spin_multiplicity: tuple[int, int] | None = None, nelements: tuple[int, int] | None = None, chemsys: str | list[str] | None = None, deprecated: bool | None = None, elements: list[str] | None = None, exclude_elements: list[str] | None = None, formula: str | list[str] | None = None, molecule_ids: MPculeID | list[MPculeID] | None = None, task_ids: str | list[str] | None = None, num_chunks: int | None = None, chunk_size: int = 1000, all_fields: bool = True, fields: list[str] | None = None)

Query molecule docs using a variety of search criteria.

Parameters:

• charge (Tuple[int, int]) – Minimum and maximum charge for the molecule.

• spin_multiplicity (Tuple[int, int]) – Minimum and maximum spin for the molecule.

• nelements (Tuple[int, int]) – Minimum and maximum number of elements

• chemsys (str, List[str]) – A chemical system, list of chemical systems (e.g., Li-C-O, [C-O-H-N, Li-N]).

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

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

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

• formula (str, List[str]) – An alphabetical formula or list of formulas (e.g. “C2 Li2 O4”, [“C2 H4”, “C2 H6”]).

• molecule_ids (MPculeID, List[MPculeID]) – List of Materials Project Molecule IDs (MPculeIDs) to return data for.

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

• 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 MoleculeDoc to return data for. Default is molecule_id, last_updated, and formula_alphabetical if all_fields is False.

Returns:

([MoleculeDoc]) List of molecules documents