structuretoolkit.build.materialsproject.search

structuretoolkit.build.materialsproject.search(chemsys: str | list[str], fields: Iterable[str] = (), api_key=None, **kwargs) → Generator[dict[str, Any], None, None]

Search the database for all structures matching the given query.

Note that chemsys takes distinct values for unaries, binaries and so! A query with chemsys=[“Fe”, “O”] will return iron and oxygen structures but not iron oxide. Similarly chemsys=[“Fe-O”] will not return unary structures.

All keyword arguments for filtering from the original API are supported. See the original docs for them.

Search for all iron structures:

>>> irons = structuretoolkit.build.materialsproject.search("Fe")
>>> len(list(irons))
10

Search for all structures with Al, Li that are on the T=0 convex hull:

>>> alli = structuretoolkit.build.materialsproject.search(['Al', 'Li', 'Al-Li'], is_stable=True)
>>> len(list(alli))
6

Usage is only possible with an API key obtained from the Materials Project. To do this, create an account with them, login and access this webpage <https://next-gen.materialsproject.org/api#api-key>.

Once you have a key, either pass it as the api_key parameter or export an environment variable, called MP_API_KEY, in your shell setup.

Parameters:

• chemsys (str, list of str) – confine search to given elements; either an element symbol or multiple element symbols separated by dashes; if a list of strings is given return structures matching either of them

• fields (iterable of str) – pass as fields to mp_api.MPRester.summary.search() to request additional database entries beyond the structure

• api_key (str, optional) – if your API key is not exported in the environment flag MP_API_KEY, pass it here

• **kwargs – passed verbatim to mp_api.MPRester.summary.search() to further filter the results

Returns:

one dictionary for each search results with at least keys

’material_id’: database key of the hit ‘structure’: ASE atoms object plus any requested via fields.

Return type:

list of dict