ocpapi.workflows.adsorbates

ocpapi.workflows.adsorbates#

Attributes#

`_CTX_AD_BULK`
`_CTX_SLAB`
`DEFAULT_CLIENT`
`_DEFAULT_ADSLAB_FILTER`

Exceptions#

`AdsorbatesException`	Base exception for all others in this module.
`UnsupportedModelException`	Exception raised when a model is not supported in the API.
`UnsupportedBulkException`	Exception raised when a bulk material is not supported in the API.
`UnsupportedAdsorbateException`	Exception raised when an adsorbate is not supported in the API.

Classes#

`Lifetime`	Represents different lifetimes when running relaxations.
`AdsorbateSlabRelaxations`	Stores the relaxations of adsorbate placements on the surface of a slab.
`AdsorbateBindingSites`	Stores the inputs and results of a set of relaxations of adsorbate

Functions#

`_setup_log_record_factory`(→ None)	Adds a log record factory that stores information about the currently
`_ensure_model_supported`(→ None)	Checks that the input model is supported in the API.
`_get_bulk_if_supported`(→ fairchem.demo.ocpapi.client.Bulk)	Returns the object from the input bulk if it is supported in the API.
`_ensure_adsorbate_supported`(→ None)	Checks that the input adsorbate is supported in the API.
`_get_slabs`(→ list[fairchem.demo.ocpapi.client.Slab])	Enumerates surfaces for the input bulk material.
`_get_absorbate_configs_on_slab`(...)	Generate initial guesses at adsorbate binding sites on the input slab.
`_get_absorbate_configs_on_slab_with_logging`(...)	Wrapper around _get_absorbate_configs_on_slab that adds logging.
`_get_adsorbate_configs_on_slabs`(...)	Finds candidate adsorbate binding sites on each of the input slabs.
`_submit_relaxations`(→ str)	Start relaxations for each of the input adsorbate configurations on the
`_submit_relaxations_with_progress_logging`(→ str)	Wrapper around _submit_relaxations that adds periodic logging in case
`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
`_delete_system`(→ None)	Deletes the input system, with retries on failed attempts.
`_ensure_system_deleted`(→ AsyncGenerator[None, None])	Immediately yields control to the caller. When control returns to this
`_run_relaxations_on_slab`(→ AdsorbateSlabRelaxations)	Start relaxations for each adsorbate configuration on the input slab
`_refresh_pbar`(→ None)	Helper function that refreshes the input progress bar on a regular
`_relax_binding_sites_on_slabs`(→ AdsorbateBindingSites)	Search for adsorbate binding sites on the input slab.
`find_adsorbate_binding_sites`(→ AdsorbateBindingSites)	Search for adsorbate binding sites on surfaces of a bulk material.

Module Contents#

ocpapi.workflows.adsorbates._CTX_AD_BULK: contextvars.ContextVar[tuple[str, str]]#

ocpapi.workflows.adsorbates._CTX_SLAB: contextvars.ContextVar[fairchem.demo.ocpapi.client.Slab]#

ocpapi.workflows.adsorbates._setup_log_record_factory() → None#: Adds a log record factory that stores information about the currently running job on a log message.

ocpapi.workflows.adsorbates.DEFAULT_CLIENT: fairchem.demo.ocpapi.client.Client#

exception ocpapi.workflows.adsorbates.AdsorbatesException#

Bases: Exception

Base exception for all others in this module.

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

Bases: AdsorbatesException

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

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

Bases: AdsorbatesException

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

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

Bases: AdsorbatesException

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

class ocpapi.workflows.adsorbates.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.

class ocpapi.workflows.adsorbates.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.adsorbates.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.

async ocpapi.workflows.adsorbates._ensure_model_supported(client: fairchem.demo.ocpapi.client.Client, model: str) → None#

Checks that the input model is supported in the API.

Parameters:

client – The client to use when making requests to the API.
model – The model to check.

Raises:

UnsupportedModelException – If the model is not supported.

async ocpapi.workflows.adsorbates._get_bulk_if_supported(client: fairchem.demo.ocpapi.client.Client, bulk: str) → fairchem.demo.ocpapi.client.Bulk#

Returns the object from the input bulk if it is supported in the API.

Parameters:

client – The client to use when making requests to the API.
bulk – The bulk to fetch.

Raises:

UnsupportedBulkException – If the requested bulk is not supported.

Returns:

Bulk instance for the input type.

async ocpapi.workflows.adsorbates._ensure_adsorbate_supported(client: fairchem.demo.ocpapi.client.Client, adsorbate: str) → None#

Checks that the input adsorbate is supported in the API.

Parameters:

client – The client to use when making requests to the API.
adsorbate – The adsorbate to check.

Raises:

UnsupportedAdsorbateException – If the adsorbate is not supported.

async ocpapi.workflows.adsorbates._get_slabs(client: fairchem.demo.ocpapi.client.Client, bulk: fairchem.demo.ocpapi.client.Bulk) → list[fairchem.demo.ocpapi.client.Slab]#

Enumerates surfaces for the input bulk material.

Parameters:

client – The client to use when making requests to the API.
bulk – The bulk material from which slabs will be generated.

Returns:

The list of slabs that were generated.

async ocpapi.workflows.adsorbates._get_absorbate_configs_on_slab(client: fairchem.demo.ocpapi.client.Client, adsorbate: str, slab: fairchem.demo.ocpapi.client.Slab) → fairchem.demo.ocpapi.client.AdsorbateSlabConfigs#

Generate initial guesses at adsorbate binding sites on the input slab.

Parameters:

client – The client to use when making API calls.
adsorbate – Description of the adsorbate to place.
slab – The slab on which the adsorbate should be placed.

Returns:

An updated slab instance that has had tags applied to it and a list of Atoms objects, each with the positions of the adsorbate atoms on one of the candidate binding sites.

async ocpapi.workflows.adsorbates._get_absorbate_configs_on_slab_with_logging(client: fairchem.demo.ocpapi.client.Client, adsorbate: str, slab: fairchem.demo.ocpapi.client.Slab) → fairchem.demo.ocpapi.client.AdsorbateSlabConfigs#: Wrapper around _get_absorbate_configs_on_slab that adds logging.

async ocpapi.workflows.adsorbates._get_adsorbate_configs_on_slabs(client: fairchem.demo.ocpapi.client.Client, adsorbate: str, slabs: list[fairchem.demo.ocpapi.client.Slab]) → list[fairchem.demo.ocpapi.client.AdsorbateSlabConfigs]#

Finds candidate adsorbate binding sites on each of the input slabs.

Parameters:

client – The client to use when making API calls.
adsorbate – Description of the adsorbate to place.
slabs – The slabs on which the adsorbate should be placed.

Returns:

List of slabs and, for each, the positions of the adsorbate atoms in the potential binding site.

async ocpapi.workflows.adsorbates._submit_relaxations(client: fairchem.demo.ocpapi.client.Client, adsorbate: str, adsorbate_configs: list[fairchem.demo.ocpapi.client.Atoms], bulk: fairchem.demo.ocpapi.client.Bulk, slab: fairchem.demo.ocpapi.client.Slab, model: str, ephemeral: bool) → str#

Start relaxations for each of the input adsorbate configurations on the input slab.

Parameters:

client – The client to use when making API calls.
adsorbate – Description of the adsorbate to place.
adsorbate_configs – Positions of the adsorbate on the slab. Each will be relaxed independently.
bulk – The bulk material from which the slab was generated.
slab – The slab that should be searched for adsorbate binding sites.
model – The model to use when evaluating forces and energies.
ephemeral – Whether the relaxations should be marked as ephemeral.

Returns:

The system ID of the relaxation run, which can be used to fetch results as they become available.

async ocpapi.workflows.adsorbates._submit_relaxations_with_progress_logging(client: fairchem.demo.ocpapi.client.Client, adsorbate: str, adsorbate_configs: list[fairchem.demo.ocpapi.client.Atoms], bulk: fairchem.demo.ocpapi.client.Bulk, slab: fairchem.demo.ocpapi.client.Slab, model: str, ephemeral: bool) → str#: Wrapper around _submit_relaxations that adds periodic logging in case calls to submit relaxations are being rate limited.

async ocpapi.workflows.adsorbates.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.adsorbates.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.

async ocpapi.workflows.adsorbates._delete_system(client: fairchem.demo.ocpapi.client.Client, system_id: str) → None#

Deletes the input system, with retries on failed attempts.

Parameters:

client – The client to use when making API calls.
system_id – The ID of the system to delete.

async ocpapi.workflows.adsorbates._ensure_system_deleted(client: fairchem.demo.ocpapi.client.Client, system_id: str) → AsyncGenerator[None, None]#

Immediately yields control to the caller. When control returns to this function, try to delete the system with the input id.

Parameters:

client – The client to use when making API calls.
system_id – The ID of the system to delete.

async ocpapi.workflows.adsorbates._run_relaxations_on_slab(client: fairchem.demo.ocpapi.client.Client, adsorbate: str, adsorbate_configs: list[fairchem.demo.ocpapi.client.Atoms], bulk: fairchem.demo.ocpapi.client.Bulk, slab: fairchem.demo.ocpapi.client.Slab, model: str, lifetime: Lifetime, pbar: tqdm.tqdm) → AdsorbateSlabRelaxations#

Start relaxations for each adsorbate configuration on the input slab and wait for all to finish.

Parameters:

client – The client to use when making API calls.
adsorbate – Description of the adsorbate to place.
adsorbate_configs – The positions of atoms in each adsorbate placement to be relaxed.
bulk – The bulk material from which the slab was generated.
slab – The slab that should be searched for adsorbate binding sites.
model – The model to use when evaluating forces and energies.
lifetime – Whether relaxations should be saved on the server, be marked as ephemeral (allowing them to deleted in the future), or deleted immediately.
pbar – A progress bar to update as relaxations finish.

Returns:

Details of each adsorbate placement, including its relaxed position.

async ocpapi.workflows.adsorbates._refresh_pbar(pbar: tqdm.tqdm, interval_sec: float) → None#

Helper function that refreshes the input progress bar on a regular schedule. This function never returns; it must be cancelled.

Parameters:

pbar – The progress bar to refresh.
interval_sec – The number of seconds to wait between each refresh.

async ocpapi.workflows.adsorbates._relax_binding_sites_on_slabs(client: fairchem.demo.ocpapi.client.Client, adsorbate: str, bulk: fairchem.demo.ocpapi.client.Bulk, adslabs: list[fairchem.demo.ocpapi.client.AdsorbateSlabConfigs], model: str, lifetime: Lifetime) → AdsorbateBindingSites#

Search for adsorbate binding sites on the input slab.

Parameters:

client – The client to use when making API calls.
adsorbate – Description of the adsorbate to place.
bulk – The bulk material from which the slab was generated.
adslabs – The slabs and, for each, the binding sites that should be relaxed.
model – The model to use when evaluating forces and energies.
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 placement, including its relaxed position.

ocpapi.workflows.adsorbates._DEFAULT_ADSLAB_FILTER: Callable[[list[fairchem.demo.ocpapi.client.AdsorbateSlabConfigs]], Awaitable[list[fairchem.demo.ocpapi.client.AdsorbateSlabConfigs]]]#

async ocpapi.workflows.adsorbates.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.