pyiron_atomistics.atomistics.structure.factories.materialsproject.MaterialsProjectFactory

class pyiron_atomistics.atomistics.structure.factories.materialsproject.MaterialsProjectFactory

Bases: object

Convenience interface to the Materials Project Structure Database.

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 in the methods of this object or export an environment variable, called MP_API_KEY, in your shell setup.

__init__()

Methods

__init__()
by_id(material_id[, final, ...])	Retrieve a structure by material id.
search(chemsys[, api_key])	Search the database for all structures matching the given query.

static by_id(material_id: str | int, final: bool = True, conventional_unit_cell: bool = False, api_key=None) → Atoms | List[Atoms]

Retrieve a structure by material id.

This is how you would ask for the iron ground state:

>>> pr = Project(...)
>>> pr.create.structure.materialsproject.by_id('mp-13')
Fe: [0. 0. 0.]
tags:
    spin: [(0: 2.214)]
pbc: [ True  True  True]
cell:
Cell([[2.318956, 0.000185, -0.819712], [-1.159251, 2.008215, -0.819524], [2.5e-05, 0.000273, 2.459206]])

Parameters:

• material_id (str) – the id assigned to a structure by the materials project

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

• final (bool, optional) – if set to False, returns the list of initial structures,

• structure. (else returns the final)

• conventional_unit_cell (bool, optional) – if set to True, returns the standard conventional unit cell.

• False) ((Default is)

Returns:

requested final structure if final is True list of :class:~.Atoms`: a list of initial (pre-relaxation) structures if final is False

Return type:

Atoms

Raises:

ValueError – material id does not exist

static search(chemsys: str | List[str], api_key=None, **kwargs) → MPQueryResults

Search the database for all structures matching the given query.

Note that chemsys takes distint values for unaries, binaries and so! A query with chemsys=[“Fe”, “O”] will return iron structures and oxygen structures, but no iron oxide structures. Similarily 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:

>>> pr = Project(...)
>>> irons = pr.create.structure.materialsproject.search("Fe")
>>> irons.number_of_structures
10

The returned MPQueryResults object implements HasStructure and can be accessed with the material ids as a short-hand

>>> irons.get_structure(1) == irons.get_structure('mp-13')
True

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

>>> alli = pr.create.structure.materialsproject.search(['Al', 'Li', 'Al-Li'], is_stable=True)
>>> len(alli)
6

Parameters:

• chemsys (str, list of str) – confine search to given elements; either an element symbol or multiple element

• them (symbols seperated by dashes; if a list of strings is given return structures matching either of)

• 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:

resulting structures from the query

Return type:

MPQueryResults