client

This module provides classes for retrieving crystallographic data from online databases like the Crystallography Open Database (COD) and Materials Project.

class fpfunctions.client.Provider(name, base_url, description, homepage, prefix)

Bases: tuple

_asdict()

Return a new dict which maps field names to their values.

_field_defaults = {}

_fields = ('name', 'base_url', 'description', 'homepage', 'prefix')

classmethod _make(iterable)

Make a new Provider object from a sequence or iterable

_replace(**kwds)

Return a new Provider object replacing specified fields with new values

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

class fpfunctions.client.ClientOptimade(aliases_or_resource_urls: str | List[str] | None = None, timeout: int = 5)

Bases: object

This class is a simplified version of the OptimadeRester, from Pymatgen, it just retrieves id’s from queries TODO: Implement the optimade client but using the Client features of the optimade python tools

aliases: Dict[str, str] = {'cod': 'https://www.crystallography.net/cod/optimade/', 'mp': 'https://optimade.materialsproject.org'}

__init__(aliases_or_resource_urls: str | List[str] | None = None, timeout: int = 5) → None

Initialize the ClientOptimade with specified OPTIMADE providers.

Parameters:

• aliases_or_resource_urls – String or list of strings representing provider aliases or URLs. If None, connects to all known providers.

• timeout – Request timeout in seconds.

describe() → str

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

Returns:

A formatted string with details about connected providers.

_get_json(url: str) → Dict

Retrieves JSON from a URL.

Parameters:

url – The URL to retrieve JSON data from.

Returns:

The JSON response as a dictionary.

get_id_with_filter(optimade_filter: str) → Dict[str, List[str]]

Get structure IDs from OPTIMADE providers using a filter string.

Parameters:

optimade_filter – OPTIMADE filter string to query structures.

Returns:

Dictionary mapping provider identifiers to lists of structure IDs.

static _get_id_from_resource(json: Dict, url: str) → List[str]

Extract structure IDs from an OPTIMADE API response.

Parameters:

• json – JSON response from an OPTIMADE API call.

• url – The URL that was used to retrieve the JSON data.

Returns:

List of structure IDs extracted from the response.

_validate_provider(provider_url: str) → Provider | None

Checks that a given URL is indeed an OPTIMADE provider.

Parameters:

provider_url – URL to validate as an OPTIMADE provider.

Returns:

Provider namedtuple if the URL is a valid OPTIMADE provider, None otherwise.

TODO: careful reading of OPTIMADE specification required TODO: add better exception handling, intentionally permissive currently

_parse_provider(provider: str, provider_url: str) → Dict[str, Provider]

Used internally to update the list of providers or to check a given URL is valid.

It does not raise exceptions but will instead log warnings and provide an empty dictionary in the case of invalid data.

Parameters:

• provider – The provider prefix.

• provider_url – An OPTIMADE provider URL.

Returns:

A dictionary of keys (in format of “provider.database”) to Provider objects.

Note

In future, when the specification is sufficiently well adopted, we might be more strict here.

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

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

Parameters:

providers_url – URL to the OPTIMADE providers registry JSON file.

class fpfunctions.client.Client(provider: str, selected_elements: Dict[str, int], terminal)

Bases: object

__init__(provider: str, selected_elements: Dict[str, int], terminal) → None

Initialize a Client instance for retrieving crystallographic data.

Parameters:

• provider – The provider name (‘mp’ for Materials Project or ‘cod’ for Crystallography Open Database).

• selected_elements – Dictionary mapping element symbols to their selection status (0: excluded, 1: optional, 2: required).

• terminal – Terminal object for displaying status messages.

static _build_custom_optimade_filter(selected_elements: Dict[str, int]) → str

Build an OPTIMADE filter string based on selected elements.

This is a rewritten filter generator from PyMatgen customized for our needs.

Parameters:

selected_elements – Dictionary mapping element symbols to their selection status (0: excluded, 1: optional, 2: required).

Returns:

OPTIMADE filter string for querying structures with the specified element constraints.

Raises:

• ValueError – If an element has an invalid status value.

• TypeError – If the keys in the selection dictionary are not strings.

_run_optimade_client() → Dict[str, List[str]]

Run the OPTIMADE client to retrieve structure IDs based on selected elements.

This method connects to the specified provider’s OPTIMADE API, applies the filter generated from selected elements, and retrieves matching structure IDs.

Returns:

Dictionary mapping provider identifiers to lists of structure IDs.

get_urls() → List[str]

Generate URLs for downloading CIF files from the selected provider.

This method retrieves structure IDs from the OPTIMADE API and constructs appropriate URLs for downloading CIF files based on the provider.

Returns:

List of URLs for downloading CIF files.