mp_api.client.routes.materials.chemenv.ChemenvRester

class mp_api.client.routes.materials.chemenv.ChemenvRester(api_key: str | None = None, endpoint: str | None = None, include_user_agent: bool = True, session: requests.Session | None = None, s3_client: Any | None = None, debug: bool = False, monty_decode: bool = True, use_document_model: bool = True, timeout: int = 20, headers: dict | None = None, mute_progress_bars: bool = False)[source]

Bases: BaseRester[ChemEnvDoc]

Initialize the REST API helper class.

Parameters:

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

  • s3_client – boto3 S3 client object with which to connect to the object stores.ct to the object stores.ct to the object stores.

  • 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 – Custom headers for localhost connections.

  • mute_progress_bars – Whether to disable progress bars.

__init__(api_key: str | None = None, endpoint: str | None = None, include_user_agent: bool = True, session: requests.Session | None = None, s3_client: Any | None = None, debug: bool = False, monty_decode: bool = True, use_document_model: bool = True, timeout: int = 20, headers: dict | None = None, mute_progress_bars: bool = False)

Initialize the REST API helper class.

Parameters:

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

  • s3_client – boto3 S3 client object with which to connect to the object stores.ct to the object stores.ct to the object stores.

  • 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 – Custom headers for localhost connections.

  • mute_progress_bars – Whether to disable progress bars.

Methods

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

Initialize the REST API helper class.

count([criteria])

Return a count of total documents.

get_data_by_id(document_id[, fields])

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

Query for chemical environment data.

Attributes

available_fields

primary_key

s3_client

session

suffix

supports_versions

document_model

alias of ChemEnvDoc

search(material_ids: str | list[str] | None = None, chemenv_iucr: Literal['[8do]', '[3n]', '[6p]', '[8cb]', '[5by]', '[12p]', '[6p2c]', '[8acb]', '[7by]', '[3l]', '[6p1c]', '[12aco]', '[2l]', 'None', '[12i]', '[6o]', '[6p3c]', '[4n]', '[12co]', '[1l]', '[5y]', '[5l]', '[4l]', '[2n]', '[8by]', '[4t]', '[12tt]'] | list[Literal['[8do]', '[3n]', '[6p]', '[8cb]', '[5by]', '[12p]', '[6p2c]', '[8acb]', '[7by]', '[3l]', '[6p1c]', '[12aco]', '[2l]', 'None', '[12i]', '[6o]', '[6p3c]', '[4n]', '[12co]', '[1l]', '[5y]', '[5l]', '[4l]', '[2n]', '[8by]', '[4t]', '[12tt]']] | None = None, chemenv_iupac: Literal['TOCT-9', 'CUS-10', 'PPR-10', 'PPRP-11', 'OCF-7', 'SAPRT-10', 'T-4', 'PAPR-10', 'DD-20', 'TPR-6', 'OCT-8', 'PP-5', 'SPY-4', 'HBPY-9', 'A-2', 'TPRT-8', 'TS-3', 'SS-4', 'None', 'SAPR-8', 'SPY-5', 'SAPRS-10', 'HPR-12', 'L-2', 'PPY-6', 'SP-4', 'IC-12', 'HBPY-8', 'TPY-3', 'CUS-9', 'TPRS-8', 'DD-8', 'TBPY-5', 'TP-3', 'TCA-9', 'PPRP-12', 'SAPRS-9', 'OC-6', 'PBPY-7', 'TPRS-7', 'TPRS-9', 'CU-8', 'HAPR-12', 'TPRT-7'] | list[Literal['TOCT-9', 'CUS-10', 'PPR-10', 'PPRP-11', 'OCF-7', 'SAPRT-10', 'T-4', 'PAPR-10', 'DD-20', 'TPR-6', 'OCT-8', 'PP-5', 'SPY-4', 'HBPY-9', 'A-2', 'TPRT-8', 'TS-3', 'SS-4', 'None', 'SAPR-8', 'SPY-5', 'SAPRS-10', 'HPR-12', 'L-2', 'PPY-6', 'SP-4', 'IC-12', 'HBPY-8', 'TPY-3', 'CUS-9', 'TPRS-8', 'DD-8', 'TBPY-5', 'TP-3', 'TCA-9', 'PPRP-12', 'SAPRS-9', 'OC-6', 'PBPY-7', 'TPRS-7', 'TPRS-9', 'CU-8', 'HAPR-12', 'TPRT-7']] | None = None, chemenv_name: Literal['Pentagonal pyramid', 'Metabidiminished icosahedron', 'Square-face bicapped trigonal prism', 'Pentagonal plane', 'Cube', 'Triangular cupola', 'Heptagonal dipyramid', 'Pentagonal prism', 'T-shaped', 'Square-face capped trigonal prism', 'Single neighbor', 'Triangular-face bicapped trigonal prism', 'Pentagonal-face capped pentagonal antiprism', 'Trigonal prism', 'Square cupola', 'See-saw', 'Square non-coplanar', 'Hexagonal bipyramid', 'Triangular non-coplanar', 'Tetrahedron', 'Tricapped triangular prism (one square-face cap and two triangular-face caps)', 'Square-face monocapped antiprism', 'Hexagonal antiprism', 'Linear', 'Octahedron', 'Truncated tetrahedron', 'Square-face capped hexagonal prism', 'Tricapped octahedron (all 3 cap faces share one atom)', 'Bicapped square prism (opposite faces)', 'Bicapped octahedron (cap faces with one edge in common)', 'Tridiminished icosahedron', 'Cuboctahedron', 'Dodecahedron', 'Dodecahedron with triangular faces - p2345 plane normalized', 'Square-face capped square prism', 'Icosahedron', 'Dodecahedron with triangular faces', 'Pentagonal bipyramid', 'Tricapped octahedron (cap faces are aligned)', 'Square pyramid', 'Tricapped triangular prism (three square-face caps)', 'Trigonal bipyramid', 'Tricapped triangular prism (two square-face caps and one triangular-face cap)', 'Pentagonal antiprism', 'Diminished icosahedron', 'Anticuboctahedron', 'Trigonal-face bicapped square antiprism', 'Bicapped octahedron (cap faces with one atom in common)', 'Hexagonal prism', 'Angular', 'Trigonal plane', 'Square plane', 'Bicapped octahedron (opposed cap faces)', 'Bicapped square prism (adjacent faces)', 'Square antiprism', 'Pentagonal-face bicapped pentagonal prism', 'Square-face bicapped square antiprism', 'Hendecahedron', 'End-trigonal-face capped trigonal prism', 'Face-capped octahedron', 'Tricapped octahedron (all 3 cap faces are sharingone edge of a face)'] | list[Literal['Pentagonal pyramid', 'Metabidiminished icosahedron', 'Square-face bicapped trigonal prism', 'Pentagonal plane', 'Cube', 'Triangular cupola', 'Heptagonal dipyramid', 'Pentagonal prism', 'T-shaped', 'Square-face capped trigonal prism', 'Single neighbor', 'Triangular-face bicapped trigonal prism', 'Pentagonal-face capped pentagonal antiprism', 'Trigonal prism', 'Square cupola', 'See-saw', 'Square non-coplanar', 'Hexagonal bipyramid', 'Triangular non-coplanar', 'Tetrahedron', 'Tricapped triangular prism (one square-face cap and two triangular-face caps)', 'Square-face monocapped antiprism', 'Hexagonal antiprism', 'Linear', 'Octahedron', 'Truncated tetrahedron', 'Square-face capped hexagonal prism', 'Tricapped octahedron (all 3 cap faces share one atom)', 'Bicapped square prism (opposite faces)', 'Bicapped octahedron (cap faces with one edge in common)', 'Tridiminished icosahedron', 'Cuboctahedron', 'Dodecahedron', 'Dodecahedron with triangular faces - p2345 plane normalized', 'Square-face capped square prism', 'Icosahedron', 'Dodecahedron with triangular faces', 'Pentagonal bipyramid', 'Tricapped octahedron (cap faces are aligned)', 'Square pyramid', 'Tricapped triangular prism (three square-face caps)', 'Trigonal bipyramid', 'Tricapped triangular prism (two square-face caps and one triangular-face cap)', 'Pentagonal antiprism', 'Diminished icosahedron', 'Anticuboctahedron', 'Trigonal-face bicapped square antiprism', 'Bicapped octahedron (cap faces with one atom in common)', 'Hexagonal prism', 'Angular', 'Trigonal plane', 'Square plane', 'Bicapped octahedron (opposed cap faces)', 'Bicapped square prism (adjacent faces)', 'Square antiprism', 'Pentagonal-face bicapped pentagonal prism', 'Square-face bicapped square antiprism', 'Hendecahedron', 'End-trigonal-face capped trigonal prism', 'Face-capped octahedron', 'Tricapped octahedron (all 3 cap faces are sharingone edge of a face)']] | None = None, chemenv_symbol: Literal['S:1', 'L:2', 'A:2', 'TL:3', 'TY:3', 'TS:3', 'T:4', 'S:4', 'SY:4', 'SS:4', 'PP:5', 'S:5', 'T:5', 'O:6', 'T:6', 'PP:6', 'PB:7', 'ST:7', 'ET:7', 'FO:7', 'C:8', 'SA:8', 'SBT:8', 'TBT:8', 'DD:8', 'DDPN:8', 'HB:8', 'BO_1:8', 'BO_2:8', 'BO_3:8', 'TC:9', 'TT_1:9', 'TT_2:9', 'TT_3:9', 'HD:9', 'TI:9', 'SMA:9', 'SS:9', 'TO_1:9', 'TO_2:9', 'TO_3:9', 'PP:10', 'PA:10', 'SBSA:10', 'MI:10', 'BS_1:10', 'BS_2:10', 'TBSA:10', 'PCPA:11', 'H:11', 'DI:11', 'I:12', 'PBP:12', 'TT:12', 'C:12', 'AC:12', 'SC:12', 'HP:12', 'HA:12', 'SH:13', 'DD:20', 'None'] | list[Literal['S:1', 'L:2', 'A:2', 'TL:3', 'TY:3', 'TS:3', 'T:4', 'S:4', 'SY:4', 'SS:4', 'PP:5', 'S:5', 'T:5', 'O:6', 'T:6', 'PP:6', 'PB:7', 'ST:7', 'ET:7', 'FO:7', 'C:8', 'SA:8', 'SBT:8', 'TBT:8', 'DD:8', 'DDPN:8', 'HB:8', 'BO_1:8', 'BO_2:8', 'BO_3:8', 'TC:9', 'TT_1:9', 'TT_2:9', 'TT_3:9', 'HD:9', 'TI:9', 'SMA:9', 'SS:9', 'TO_1:9', 'TO_2:9', 'TO_3:9', 'PP:10', 'PA:10', 'SBSA:10', 'MI:10', 'BS_1:10', 'BS_2:10', 'TBSA:10', 'PCPA:11', 'H:11', 'DI:11', 'I:12', 'PBP:12', 'TT:12', 'C:12', 'AC:12', 'SC:12', 'HP:12', 'HA:12', 'SH:13', 'DD:20', 'None']] | None = None, species: str | list[str] | None = None, elements: str | list[str] | None = None, exclude_elements: list[str] | None = None, csm: tuple[float, float] | None = None, density: tuple[float, float] | None = None, num_elements: tuple[int, int] | None = None, num_sites: tuple[int, int] | 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[ChemEnvDoc] | list[dict][source]

Query for chemical environment data.

Parameters:

  • material_ids (str, List[str]) – Search forchemical environment associated with the specified Material IDs.

  • chemenv_iucr (COORDINATION_GEOMETRIES_IUCR, List[COORDINATION_GEOMETRIES_IUCR]) – Unique cationic species in IUCR format, e.g. “[3n]”.

  • chemenv_iupac (COORDINATION_GEOMETRIES_IUPAC, List[COORDINATION_GEOMETRIES_IUPAC]) – Unique cationic species in IUPAC format, e.g., “T-4”.

  • chemenv_name (COORDINATION_GEOMETRIES_NAMES, List[COORDINATION_GEOMETRIES_NAMES]) – Coordination environment descriptions in text form for unique cationic species, e.g. “Tetrahedron”.

  • chemenv_symbol (COORDINATION_GEOMETRIES, List[COORDINATION_GEOMETRIES]) – Coordination environment descriptions as used in ChemEnv package for unique cationic species, e.g. “T:4”.

  • species (str, List[str]) – Cationic species in the crystal structure, e.g. “Ti4+”.

  • elements (str, List[str]) – Element names in the crystal structure, e.g., “Ti”.

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

  • csm (Tuple[float,float]) – Minimum and maximum value of continuous symmetry measure to consider.

  • density (Tuple[float,float]) – Minimum and maximum density 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.

  • 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 ChemEnvDoc to return data for.

Returns:

([ChemEnvDoc], [dict]) List of chemenv documents or dictionaries.

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)