mp_api.client.routes.molecules.molecules.BaseMoleculeRester¶

class mp_api.client.routes.molecules.molecules.BaseMoleculeRester(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[MoleculeDoc]

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.
`find_molecule`(filename_or_molecule[, ...])	Finds matching molecules from the Materials Project molecules database (MPcules).
`get_data_by_id`(document_id[, fields])	Query the endpoint for a single document.
`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_resource`
`session`
`suffix`
`supports_versions`

document_model¶: alias of MoleculeDoc

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

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

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[source]¶

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 –

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]), or single formula (e.g., C2 H4).
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

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.

mp_api.client.routes.molecules.molecules.BaseMoleculeRester¶

mp-api

Navigation