crystod.search

crystod.search#

Public Materials Project API of CrystOD (the crystod-search domain).

Search the Materials Project the way its website does and download the structures, the Python form of crystod-search. A query is a formula (SrTiO3), an anonymous formula (ABO3), a chemical system (Sr-Ti-O), a list of elements (Sr,Ti,O) or material IDs (mp-5229); the answer lists formula, space group, ID, band gap, energy above the hull and number of sites, with the experimentally observed materials flagged. An API key of the Materials Project is needed (free, from https://next-gen.materialsproject.org/api), read from the MP_API_KEY environment variable or from PMG_MAPI_KEY in the pymatgen settings file, or passed as api_key=.

Searching

search_materials() – a query plus filters (experimentally observed, on the hull, energy above hull, band gap, number of sites, space group, excluded elements), as a SearchResult of Material records.
format_table() – the table crystod-search prints.
interpret_query(), resolve_space_group(), normalize_material_id() – how queries, space groups and IDs are read (mp-aaaaahtd is mp-5229).

Downloading structures

fetch_materials() – the structures of given IDs as pymatgen Structure objects, in the standardized conventional cell (default) or the standardized primitive cell.
standardize_cell() – the cell conversion on its own.
write_poscar(), poscar_text(), poscar_filename() – the POSCAR files crystod-search --get writes.

Tables

SORT_KEYS, CELL_CHOICES – the names --sort and --cell accept; POSCAR_PREFIXES – the file-name prefix of each cell (POSCAR, PPOSCAR).

Usage:

from crystod import search

result = search.search_materials("Sr-Ti-O", experimental=True)
for material in result.materials:
    print(material.label, material.formula, material.space_group)
(sr2tio4,) = search.fetch_materials("mp-5532")
search.write_poscar(sr2tio4)  # POSCAR_Sr2TiO4_I4mmm_mp-5532 (conventional)
(sr2tio4,) = search.fetch_materials("mp-5532", cell="primitive")
search.write_poscar(sr2tio4)  # PPOSCAR_Sr2TiO4_I4mmm_mp-5532

Attributes resolve lazily (PEP 562): importing this module is instant and requests and pymatgen load only on first use. Functions report bad input as ValueError through this namespace (the implementation module raises SystemExit, as the command line wants); a missing API key, a network failure or an error of the server raise MaterialsProjectError.

exception crystod.search.MaterialsProjectError[source]#

Bases: RuntimeError

The Materials Project could not answer: no or bad API key, no network, or an error reported by the server.

class crystod.search.Material(material_id, formula, space_group, space_group_number, crystal_system, band_gap, energy_above_hull, nsites, experimental, structure=None, cell=None, deprecated=False, cell_space_group_number=None)[source]#

Bases: object

One material of the Materials Project, as a row of the search table.

Variables:

material_id (str) – The ID as the website writes it (mp-5229).
formula (str) – The reduced formula (SrTiO3).
space_group (str) – The Hermann-Mauguin symbol (Pm-3m, P6_3/mmc).
space_group_number (int) – 1-230.
crystal_system (str) – Cubic, Tetragonal, …
band_gap (float | None) – The computed band gap in eV (None when not computed).
energy_above_hull (float | None) – The energy above the convex hull in eV/atom.
nsites (int) – Number of sites of the stored (computed) cell.
experimental (bool) – True when the structure matches an experimentally observed one (an ICSD or other experimental entry); these are starred in the table.
structure (Any) – The downloaded pymatgen Structure – set by fetch_materials() (in the cell it was asked for), None in search results.
cell (str | None) – The cell structure is in (see CELL_CHOICES).
deprecated (bool) – The Materials Project has deprecated this entry.
cell_space_group_number (int | None) – The space group spglib finds for structure – set by fetch_materials(); it differs from space_group_number only when the standardization at the chosen tolerance lands on another group.

classmethod from_document(doc)[source]#

A record from one document of the materials/summary endpoint.

Return type:: Material

band_gap: float | None#

cell: str | None = None#

cell_space_group_number: int | None = None#

crystal_system: str#

deprecated: bool = False#

energy_above_hull: float | None#

experimental: bool#

formula: str#

property label: str#: The ID with the star of an experimentally observed material.

material_id: str#

nsites: int#

space_group: str#

space_group_number: int#

structure: Any = None#

property url: str#: The page of the material on the Materials Project website.

class crystod.search.SearchResult(query, description, materials, total, sort='ehull', filters=())[source]#

Bases: object

The answer to one search.

Variables:

query (str) – The query as given.
description (str) – How it was read (chemical system Sr-Ti-O, …).
materials (list[crystod.mp_search.Material]) – The matches, in the order of sort.
total (int) – How many materials match; more than len(materials) when the list was cut at max_results.
sort (str) – The key of SORT_KEYS the list is sorted by.
filters (tuple[str, ...]) – One phrase per filter that was applied.

table_lines()[source]#

The table of format_table() for these materials.

Return type:: list[str]

description: str#

filters: tuple[str, ...] = ()#

materials: list[Material]#

query: str#

sort: str = 'ehull'#

total: int#

property truncated: bool#: True when more materials match than were listed.

crystod.search.fetch_materials(material_ids, *, cell='conventional', tolerance=0.1, api_key=None)[source]#

Download the structures of the given materials.

Parameters:

material_ids (str | list[str] | tuple[str, ...]) – One ID or a list (mp-5229, mp-aaaaahtd, …).
cell (str) – "conventional" (default) or "primitive" (see standardize_cell()).
tolerance (float) – Symmetry tolerance of the standardization in Angstrom.
api_key (str | None) – The API key; by default read as find_api_key() describes.

Returns:

One Material per distinct material, in the order first given (a repeated ID, or the two spellings mp-5229 and mp-aaaaahtd of one ID, give one entry), with structure and cell_space_group_number set.

Raises:

SystemExit – A malformed ID, an ID the Materials Project does not have, or a tolerance that is not a positive number (ValueError through crystod.search).
MaterialsProjectError – No API key, no network, or a server error.

Return type:

list[Material]

crystod.search.format_table(materials)[source]#

The search table as text lines, one header line and one line per material.

Formula, space group and ID are left-aligned, the numbers right-aligned; an experimentally observed material has " *" (a space and a star) after its ID.

Return type:: list[str]

crystod.search.interpret_query(query, subsystems=False)[source]#

Read a query the way the Materials Project website does.

Returns:: a phrase for the header of the table and the filter parameters of the materials/summary endpoint.
Return type:: (description, criteria)
Raises:: SystemExit – The query cannot be read, or subsystems is set for a query that is not a single chemical system (ValueError through crystod.search).

crystod.search.normalize_material_id(text)[source]#

The website spelling of a Materials Project ID.

mp-aaaaahtd, MP-5229 and mp-5229 all give mp-5229; an ID past LEGACY_ID_CUTOFF is given in the 8-letter alphabetical form (mp-3732049 gives mp-aaaieiuj).

Raises:: SystemExit – text is not a Materials Project ID (ValueError when called through crystod.search).
Return type:: str

crystod.search.poscar_filename(material, directory=False)[source]#

The default file name of a fetched material’s POSCAR.

{prefix}_{formula}_{space group}_{ID} with the prefix of POSCAR_PREFIXES for the cell: POSCAR_Sr2TiO4_I4mmm_mp-5532 (conventional cell), PPOSCAR_Sr2TiO4_I4mmm_mp-5532 (primitive cell). The / and _ of the space-group symbol are dropped (P6_3/mmc -> P63mmc). With directory, {formula}_{space group}_{ID}/{prefix} (Sr2TiO4_I4mmm_mp-5532/POSCAR).

Return type:: str

crystod.search.poscar_text(material)[source]#

The POSCAR of a fetched material; the comment line names its source.

Return type:: str

crystod.search.resolve_space_group(text)[source]#

(number, symbol) of a space group given by number or short symbol.

The symbol is the Hermann-Mauguin short symbol as spglib and the Materials Project write it (P6_3/mmc); the underscore of a screw axis may be left out (P63/mmc).

Raises:: SystemExit – Not a space group (ValueError through the API).
Return type:: tuple[int, str]

crystod.search.search_materials(query, *, experimental=False, stable=False, max_energy_above_hull=None, band_gap=None, nsites=None, space_group=None, exclude_elements=None, subsystems=False, sort='ehull', max_results=1000, api_key=None)[source]#

Search the Materials Project the way its website does.

Parameters:

query (str) – SrTiO3 (formula), ABO3 (anonymous formula), Sr-Ti-O (chemical system), Sr,Ti,O (elements) or mp-5229 (IDs); see interpret_query().
experimental (bool) – Only experimentally observed materials.
stable (bool) – Only materials on the convex hull.
max_energy_above_hull (float | None) – Upper bound in eV/atom.
band_gap (tuple[float, float] | None) – (min, max) in eV.
nsites (tuple[int, int] | None) – (min, max) number of sites.
space_group (str | int | None) – Number or short symbol.
exclude_elements (list[str] | tuple[str, ...] | None) – Element symbols the materials must not contain.
subsystems (bool) – With a chemical system, also every subsystem (Sr-Ti-O adds Sr, Ti, O, Sr-Ti, Sr-O and Ti-O).
sort (str) – A key of SORT_KEYS (default: energy above hull).
max_results (int) – Cap on the number of materials listed. Up to 1000 of a longer list cost one request; more (or a list longer than 1000 sorted by space group, which the server cannot sort on) need every match fetched, which is refused beyond MAX_FULL_FETCH matches.
api_key (str | None) – The API key; by default read as find_api_key() describes.

Raises:

SystemExit – Unreadable query or filter, or a list too long to fetch (ValueError through crystod.search).
MaterialsProjectError – No API key, no network, or a server error.

Return type:

SearchResult

crystod.search.standardize_cell(structure, cell='conventional', tolerance=0.1)[source]#

structure in the requested cell.

"primitive" and "conventional" are the standardized cells of spglib (standardize_cell with and without to_primitive, atoms moved onto their ideal positions), the setting CrystOD’s own analyses standardize to. The angle tolerance is 5 degrees, the value the Materials Project uses with its symprec = 0.1.

Raises:: SystemExit – Unknown cell, a tolerance that is not a positive number, or a cell spglib cannot standardize (ValueError through crystod.search).

crystod.search.write_poscar(material, path=None, *, directory=False, overwrite=False, rename_hint=True)[source]#

Write the POSCAR of a fetched material.

Parameters:

material (Material) – A material from fetch_materials().
path (str | None) – File name; default poscar_filename() (POSCAR_... for the conventional cell, PPOSCAR_... for the primitive one).
directory (bool) – Write {formula}_{space group}_{ID}/POSCAR (PPOSCAR for the primitive cell) instead.
overwrite (bool) – Replace an existing file with different content.
rename_hint (bool) – Suggest -o in the error about a file in the way (the command line turns it off where -o is not allowed).

Returns:

(path, status) with status "wrote", "kept" (an identical file was already there) or "replaced".

Raises:

SystemExit – A different file is in the way and overwrite is False, the path is a directory, or the file cannot be written (ValueError through crystod.search).

Return type:

tuple[str, str]

crystod.search.SORT_KEYS#: Sort orders of --sort: name -> (field the server sorts on, description). The server cannot sort on the space-group number (it silently ignores a nested field such as symmetry.number), so spg sorts locally. The default, the energy above the hull, is the order of the website’s table.

crystod.search.CELL_CHOICES = ('conventional', 'primitive')#: Cells --cell can write: the standardized conventional cell (default) or the standardized primitive cell.

crystod.search.POSCAR_PREFIXES = {'conventional': 'POSCAR', 'primitive': 'PPOSCAR'}#: File-name prefix of each cell: POSCAR_SrTiO3_Pm-3m_mp-5229 holds the conventional cell, PPOSCAR_... the primitive one (the P of phonopy’s PPOSCAR and of CrystOD’s 221_PPOSCAR_* examples); with --directory the prefix is the file name.

crystod.search

Contents

crystod.search#