pymatgen.ext.optimade module

Optimade support.

class OptimadeRester(aliases_or_resource_urls: str | list[str] | None = None, timeout: int = 5)

Bases: object

Class to call OPTIMADE-compliant APIs, see https://optimade.org and [1].

This class is ready to use but considered in-development and subject to change.

[1] Andersen, C.W., et al.

OPTIMADE, an API for exchanging materials data. Sci Data 8, 217 (2021). https://doi.org/10.1038/s41597-021-00974-z

OPTIMADE is an effort to provide a standardized interface to retrieve information from many different materials science databases.

This is a client to retrieve structures from OPTIMADE v1 compliant endpoints. It does not yet support all features of the OPTIMADE v1 specification but is intended as a way to quickly search an endpoint in a way familiar to users of pymatgen without needing to know the full OPTIMADE specification.

For advanced usage, please see the OPTIMADE documentation at optimade.org and consider calling the APIs directly.

For convenience, known OPTIMADE endpoints have been given aliases in pymatgen to save typing the full URL. The current list of aliases is:

aflow, cod, mcloud.sssp, mcloud.2dstructures, mcloud.2dtopo, mcloud.tc-applicability, mcloud.threedd, mcloud.scdm, mcloud.curated-cofs, mcloud.optimade-sample, mcloud.stoceriaitf, mcloud.pyrene-mofs, mcloud.li-ion-conductors, mp, odbx, omdb.omdb_production, oqmd, tcod

To refresh this list of aliases, generated from the current list of OPTIMADE providers at optimade.org, call the refresh_aliases() method.

Parameters:

• aliases_or_resource_urls – the alias or structure resource URL or a list of

• URLs (aliases or resource) –

• not (if providing the resource URL directly it should) –

• index (be an) –

• "v1/structures" (this interface can only currently access the) –

• URL (information from the specified resource) –

• timeout – number of seconds before an attempted request is abandoned, a good

• providers (timeout is useful when querying many) –

• offline (some of which may be) –

aliases: dict[str, str] = {'aflow': 'http://aflow.org/API/optimade/', 'cod': 'https://www.crystallography.net/cod/optimade', 'mcloud.2dstructures': 'https://aiida.materialscloud.org/2dstructures/optimade', 'mcloud.2dtopo': 'https://aiida.materialscloud.org/2dtopo/optimade', 'mcloud.curated-cofs': 'https://aiida.materialscloud.org/curated-cofs/optimade', 'mcloud.li-ion-conductors': 'https://aiida.materialscloud.org/li-ion-conductors/optimade', 'mcloud.optimade-sample': 'https://aiida.materialscloud.org/optimade-sample/optimade', 'mcloud.pyrene-mofs': 'https://aiida.materialscloud.org/pyrene-mofs/optimade', 'mcloud.scdm': 'https://aiida.materialscloud.org/autowannier/optimade', 'mcloud.sssp': 'https://aiida.materialscloud.org/sssplibrary/optimade', 'mcloud.stoceriaitf': 'https://aiida.materialscloud.org/stoceriaitf/optimade', 'mcloud.tc-applicability': 'https://aiida.materialscloud.org/tc-applicability/optimade', 'mcloud.threedd': 'https://aiida.materialscloud.org/3dd/optimade', 'mp': 'https://optimade.materialsproject.org', 'mpds': 'https://api.mpds.io', 'nmd': 'https://nomad-lab.eu/prod/rae/optimade/', 'odbx': 'https://optimade.odbx.science', 'omdb.omdb_production': 'http://optimade.openmaterialsdb.se', 'oqmd': 'http://oqmd.org/optimade/', 'tcod': 'https://www.crystallography.net/tcod/optimade'}

describe()

Provides human-readable information about the resources being searched by the OptimadeRester.

get_snls(elements: list[str] | str | None = None, nelements: int | None = None, nsites: int | None = None, chemical_formula_anonymous: str | None = None, chemical_formula_hill: str | None = None, additional_response_fields: str | list[str] | set[str] | None = None) → dict[str, dict[str, StructureNL]]

Retrieve StructureNL from OPTIMADE providers.

A StructureNL is an object provided by pymatgen which combines Structure with associated metadata, such as the URL is was downloaded from and any additional namespaced data.

Not all functionality of OPTIMADE is currently exposed in this convenience method. To use a custom filter, call get_structures_with_filter().

Parameters:

• elements – List of elements

• nelements – Number of elements, e.g. 4 or [2, 5] for the range >=2 and <=5

• nsites – Number of sites, e.g. 4 or [2, 5] for the range >=2 and <=5

• chemical_formula_anonymous – Anonymous chemical formula

• chemical_formula_hill – Chemical formula following Hill convention

• additional_response_fields – Any additional fields desired from the OPTIMADE API,

• dictionary. (these will be stored under the '_optimade' key in each StructureNL.data) –

Returns: Dict of (Dict of StructureNLs keyed by that database’s id system) keyed by provider

get_snls_with_filter(optimade_filter: str, additional_response_fields: str | list[str] | set[str] | None = None) → dict[str, dict[str, StructureNL]]

Get structures satisfying a given OPTIMADE filter.

Parameters:

• optimade_filter – An OPTIMADE-compliant filter

• additional_response_fields – Any additional fields desired from the OPTIMADE API,

Returns: Dict of Structures keyed by that database’s id system

get_structures(elements: list[str] | str | None = None, nelements: int | None = None, nsites: int | None = None, chemical_formula_anonymous: str | None = None, chemical_formula_hill: str | None = None) → dict[str, dict[str, Structure]]

Retrieve Structures from OPTIMADE providers.

Not all functionality of OPTIMADE is currently exposed in this convenience method. To use a custom filter, call get_structures_with_filter().

Parameters:

• elements – List of elements

• nelements – Number of elements, e.g. 4 or [2, 5] for the range >=2 and <=5

• nsites – Number of sites, e.g. 4 or [2, 5] for the range >=2 and <=5

• chemical_formula_anonymous – Anonymous chemical formula

• chemical_formula_hill – Chemical formula following Hill convention

Returns: Dict of (Dict Structures keyed by that database’s id system) keyed by provider

get_structures_with_filter(optimade_filter: str) → dict[str, dict[str, pymatgen.core.structure.Structure]]

Get structures satisfying a given OPTIMADE filter.

Parameters:

optimade_filter – An OPTIMADE-compliant filter

Returns: Dict of Structures keyed by that database’s id system

mandatory_response_fields: set[str] = {'cartesian_site_positions', 'lattice_vectors', 'species', 'species_at_sites'}

refresh_aliases(providers_url='https://providers.optimade.org/providers.json')

Updates available OPTIMADE structure resources based on the current list of OPTIMADE providers.

class Provider(name, base_url, description, homepage, prefix)

Bases: tuple

Create new instance of Provider(name, base_url, description, homepage, prefix)

base_url

Alias for field number 1

description

Alias for field number 2

homepage

Alias for field number 3

name

Alias for field number 0

prefix

Alias for field number 4