ocpapi.workflows

ocpapi.workflows#

Submodules#

Attributes#

`NO_LIMIT`
`NoLimitType`

Exceptions#

`UnsupportedAdsorbateException`	Exception raised when an adsorbate is not supported in the API.
`UnsupportedBulkException`	Exception raised when a bulk material is not supported in the API.
`UnsupportedModelException`	Exception raised when a model is not supported in the API.

Classes#

`AdsorbateBindingSites`	Stores the inputs and results of a set of relaxations of adsorbate
`AdsorbateSlabRelaxations`	Stores the relaxations of adsorbate placements on the surface of a slab.
`Lifetime`	Represents different lifetimes when running relaxations.
`keep_all_slabs`	Adslab filter than returns all slabs.
`keep_slabs_with_miller_indices`	Adslab filter that keeps any slabs with the configured miller indices.
`prompt_for_slabs_to_keep`	Adslab filter than presents the user with an interactive prompt to choose
`RateLimitLogging`	Controls logging when rate limits are hit.

Functions#

`find_adsorbate_binding_sites`(→ AdsorbateBindingSites)	Search for adsorbate binding sites on surfaces of a bulk material.
`get_adsorbate_slab_relaxation_results`(...)	Wrapper around Client.get_adsorbate_slab_relaxations_results() that
`wait_for_adsorbate_slab_relaxations`(→ dict[int, ...)	Blocks until all relaxations in the input system have finished, whether
`retry_api_calls`(→ Any)	Decorator with sensible defaults for retrying calls to the OCP API.

Package Contents#

class ocpapi.workflows.AdsorbateBindingSites#

Stores the inputs and results of a set of relaxations of adsorbate placements on the surface of a slab.

adsorbate: str#: Description of the adsorbate.

bulk: fairchem.demo.ocpapi.client.Bulk#: The bulk material that was being modeled.

model: str#: The type of the model that was run.

slabs: list[AdsorbateSlabRelaxations]#: The list of slabs that were generated from the bulk structure. Each contains its own list of adsorbate placements.

class ocpapi.workflows.AdsorbateSlabRelaxations#

Stores the relaxations of adsorbate placements on the surface of a slab.

slab: fairchem.demo.ocpapi.client.Slab#: The slab on which the adsorbate was placed.

configs: list[fairchem.demo.ocpapi.client.AdsorbateSlabRelaxationResult]#: Details of the relaxation of each adsorbate placement, including the final position.

system_id: str#: The ID of the system that stores all of the relaxations.

api_host: str#: The API host on which the relaxations were run.

ui_url: str | None#: The URL at which results can be visualized.

class ocpapi.workflows.Lifetime(*args, **kwds)#

Bases: enum.Enum

Represents different lifetimes when running relaxations.

SAVE#: The relaxation will be available on API servers indefinitely. It will not be possible to delete the relaxation in the future.

MARK_EPHEMERAL#: The relaxation will be saved on API servers, but can be deleted at any time in the future.

DELETE#: The relaxation will be deleted from API servers as soon as the results have been fetched.

exception ocpapi.workflows.UnsupportedAdsorbateException(adsorbate: str)#

Bases: AdsorbatesException

Exception raised when an adsorbate is not supported in the API.

exception ocpapi.workflows.UnsupportedBulkException(bulk: str)#

Bases: AdsorbatesException

Exception raised when a bulk material is not supported in the API.

exception ocpapi.workflows.UnsupportedModelException(model: str, allowed_models: list[str])#

Bases: AdsorbatesException

Exception raised when a model is not supported in the API.

async ocpapi.workflows.find_adsorbate_binding_sites(adsorbate: str, bulk: str, model: str = 'equiformer_v2_31M_s2ef_all_md', adslab_filter: Callable[[list[fairchem.demo.ocpapi.client.AdsorbateSlabConfigs]], Awaitable[list[fairchem.demo.ocpapi.client.AdsorbateSlabConfigs]]] = _DEFAULT_ADSLAB_FILTER, client: fairchem.demo.ocpapi.client.Client = DEFAULT_CLIENT, lifetime: Lifetime = Lifetime.SAVE) → AdsorbateBindingSites#

Search for adsorbate binding sites on surfaces of a bulk material. This executes the following steps:

Ensure that both the adsorbate and bulk are supported in the OCP API.

Enumerate unique surfaces from the bulk material.

Enumerate likely binding sites for the input adsorbate on each of the generated surfaces.

Filter the list of generated adsorbate/slab (adslab) configurations
using the input adslab_filter.

Relax each generated surface+adsorbate structure by refining atomic positions to minimize forces generated by the input model.

Parameters:

adsorbate – Description of the adsorbate to place.
bulk – The ID (typically Materials Project MP ID) of the bulk material on which the adsorbate will be placed.
model – The type of the model to use when calculating forces during relaxations.
adslab_filter – A function that modifies the set of adsorbate/slab configurations that will be relaxed. This can be used to subselect slabs and/or adsorbate configurations.
client – The OCP API client to use.
lifetime – Whether relaxations should be saved on the server, be marked as ephemeral (allowing them to deleted in the future), or deleted immediately.

Returns:

Details of each adsorbate binding site, including results of relaxing to locally-optimized positions using the input model.

Raises:

UnsupportedModelException – If the requested model is not supported.
UnsupportedBulkException – If the requested bulk is not supported.
UnsupportedAdsorbateException – If the requested adsorbate is not supported.

async ocpapi.workflows.get_adsorbate_slab_relaxation_results(system_id: str, config_ids: list[int] | None = None, fields: list[str] | None = None, client: fairchem.demo.ocpapi.client.Client = DEFAULT_CLIENT) → list[fairchem.demo.ocpapi.client.AdsorbateSlabRelaxationResult]#

Wrapper around Client.get_adsorbate_slab_relaxations_results() that handles retries, including re-fetching individual configurations that are initially omitted.

Parameters:

client – The client to use when making API calls.
system_id – The system ID of the relaxations.
config_ids – If defined and not empty, a subset of configurations to fetch. Otherwise all configurations are returned.
fields – If defined and not empty, a subset of fields in each configuration to fetch. Otherwise all fields are returned.

Returns:

List of relaxation results, one for each adsorbate configuration in the system.

async ocpapi.workflows.wait_for_adsorbate_slab_relaxations(system_id: str, check_immediately: bool = False, slow_interval_sec: float = 30, fast_interval_sec: float = 10, pbar: tqdm.tqdm | None = None, client: fairchem.demo.ocpapi.client.Client = DEFAULT_CLIENT) → dict[int, fairchem.demo.ocpapi.client.Status]#

Blocks until all relaxations in the input system have finished, whether successfully or not.

Relaxations are queued in the API, waiting until machines are ready to run them. Once started, they can take 1-2 minutes to finish. This method initially sleeps “slow_interval_sec” seconds between each check for any relaxations having finished. Once at least one result is ready, subsequent sleeps are for “fast_interval_sec” seconds.

Parameters:

system_id – The ID of the system for which relaxations are running.
check_immediately – If False (default), sleep before the first check for relaxations having finished. If True, check whether relaxations have finished immediately on entering this function.
slow_interval_sec – The number of seconds to wait between each check while all are still running.
fast_interval_sec – The number of seconds to wait between each check when at least one relaxation has finished in the system.
pbar – A tqdm instance that tracks the number of configurations that have finished. This will be updated with the number of individual configurations whose relaxations have finished.
client – The client to use when making API calls.

Returns:

Map of config IDs in the system to their terminal status.

class ocpapi.workflows.keep_all_slabs#

Adslab filter than returns all slabs.

async __call__(adslabs: list[fairchem.demo.ocpapi.client.AdsorbateSlabConfigs]) → list[fairchem.demo.ocpapi.client.AdsorbateSlabConfigs]#

class ocpapi.workflows.keep_slabs_with_miller_indices(miller_indices: Iterable[tuple[int, int, int]])#

Adslab filter that keeps any slabs with the configured miller indices. Slabs with other miller indices will be ignored.

_unique_millers: set[tuple[int, int, int]]#

async __call__(adslabs: list[fairchem.demo.ocpapi.client.AdsorbateSlabConfigs]) → list[fairchem.demo.ocpapi.client.AdsorbateSlabConfigs]#

class ocpapi.workflows.prompt_for_slabs_to_keep#

Adslab filter than presents the user with an interactive prompt to choose which of the input slabs to keep.

static _sort_key(adslab: fairchem.demo.ocpapi.client.AdsorbateSlabConfigs) → tuple[tuple[int, int, int], float, str]#: Generates a sort key from the input adslab. Returns the miller indices, shift, and top/bottom label so that they will be sorted by those values in that order.

async __call__(adslabs: list[fairchem.demo.ocpapi.client.AdsorbateSlabConfigs]) → list[fairchem.demo.ocpapi.client.AdsorbateSlabConfigs]#

ocpapi.workflows.NO_LIMIT: NoLimitType = 0#

ocpapi.workflows.NoLimitType#

class ocpapi.workflows.RateLimitLogging#

Controls logging when rate limits are hit.

logger: logging.Logger#: The logger to use.

action: str#: A short description of the action being attempted.

ocpapi.workflows.retry_api_calls(max_attempts: int | NoLimitType = 3, rate_limit_logging: RateLimitLogging | None = None, fixed_wait_sec: float = 2, max_jitter_sec: float = 1) → Any#

Decorator with sensible defaults for retrying calls to the OCP API.

Parameters:

max_attempts – The maximum number of calls to make. If NO_LIMIT, retries will be made forever.
rate_limit_logging – If not None, log statements will be generated using this configuration when a rate limit is hit.
fixed_wait_sec – The fixed number of seconds to wait when retrying an exception that does not include a retry-after value. The default value is sensible; this is exposed mostly for testing.
max_jitter_sec – The maximum number of seconds that will be randomly added to wait times. The default value is sensible; this is exposed mostly for testing.