ocpapi.client.client

Exceptions

RequestException	Exception raised any time there is an error while making an API call.
NonRetryableRequestException	Exception raised when an API call is rejected for a reason that will
RateLimitExceededException	Exception raised when an API call is rejected because a rate limit has

Classes

Client

Exposes each route in the OCP API as a method.

Module Contents

exception ocpapi.client.client.RequestException(method: str, url: str, cause: str)

Bases: Exception

Exception raised any time there is an error while making an API call.

exception ocpapi.client.client.NonRetryableRequestException(method: str, url: str, cause: str)

Bases: RequestException

Exception raised when an API call is rejected for a reason that will not succeed on retry. For example, this might include a malformed request or action that is not allowed.

exception ocpapi.client.client.RateLimitExceededException(method: str, url: str, retry_after: datetime.timedelta | None = None)

Bases: RequestException

Exception raised when an API call is rejected because a rate limit has been exceeded.

retry_after

If known, the time to wait before the next attempt to call the API should be made.

retry_after: datetime.timedelta | None

class ocpapi.client.client.Client(host: str = 'open-catalyst-api.metademolab.com', scheme: str = 'https')

Exposes each route in the OCP API as a method.

_host

_base_url

property host: str

The host being called by this client.

async get_models() → ocpapi.client.models.Models

Fetch the list of models that are supported in the API.

Raises:

• RateLimitExceededException – If the call was rejected because a server side rate limit was breached.

• NonRetryableRequestException – If the call was rejected and a retry is not expected to succeed.

• RequestException – For all other errors when making the request; it is possible, though not guaranteed, that a retry could succeed.

Returns:

The models that are supported in the API.

async get_bulks() → ocpapi.client.models.Bulks

Fetch the list of bulk materials that are supported in the API.

Raises:

• RateLimitExceededException – If the call was rejected because a server side rate limit was breached.

• NonRetryableRequestException – If the call was rejected and a retry is not expected to succeed.

• RequestException – For all other errors when making the request; it is possible, though not guaranteed, that a retry could succeed.

Returns:

The bulks that are supported throughout the API.

async get_adsorbates() → ocpapi.client.models.Adsorbates

Fetch the list of adsorbates that are supported in the API.

Raises:

• RateLimitExceededException – If the call was rejected because a server side rate limit was breached.

• NonRetryableRequestException – If the call was rejected and a retry is not expected to succeed.

• RequestException – For all other errors when making the request; it is possible, though not guaranteed, that a retry could succeed.

Returns:

The adsorbates that are supported throughout the API.

async get_slabs(bulk: str | ocpapi.client.models.Bulk) → ocpapi.client.models.Slabs

Get a unique list of slabs for the input bulk structure.

Parameters:

bulk – If a string, the id of the bulk to use. Otherwise the Bulk instance to use.

Raises:

• RateLimitExceededException – If the call was rejected because a server side rate limit was breached.

• NonRetryableRequestException – If the call was rejected and a retry is not expected to succeed.

• RequestException – For all other errors when making the request; it is possible, though not guaranteed, that a retry could succeed.

Returns:

Slabs for each of the unique surfaces of the material.

async get_adsorbate_slab_configs(adsorbate: str, slab: ocpapi.client.models.Slab) → ocpapi.client.models.AdsorbateSlabConfigs

Get a list of possible binding sites for the input adsorbate on the input slab.

Parameters:

• adsorbate – Description of the the adsorbate to place.

• slab – Information about the slab on which the adsorbate should be placed.

Raises:

• RateLimitExceededException – If the call was rejected because a server side rate limit was breached.

• NonRetryableRequestException – If the call was rejected and a retry is not expected to succeed.

• RequestException – For all other errors when making the request; it is possible, though not guaranteed, that a retry could succeed.

Returns:

Configurations for each adsorbate binding site on the slab.

async submit_adsorbate_slab_relaxations(adsorbate: str, adsorbate_configs: list[ocpapi.client.models.Atoms], bulk: ocpapi.client.models.Bulk, slab: ocpapi.client.models.Slab, model: str, ephemeral: bool = False) → ocpapi.client.models.AdsorbateSlabRelaxationsSystem

Starts relaxations of the input adsorbate configurations on the input slab using energies and forces returned by the input model. Relaxations are run asynchronously and results can be fetched using the system id that is returned from this method.

Parameters:

• adsorbate – Description of the adsorbate being simulated.

• adsorbate_configs – List of adsorbate configurations to relax. This should only include the adsorbates themselves; the surface is defined in the “slab” field that is a peer to this one.

• bulk – Details of the bulk material being simulated.

• slab – The structure of the slab on which adsorbates are placed.

• model – The model that will be used to evaluate energies and forces during relaxations.

• ephemeral – If False (default), any later attempt to delete the generated relaxations will be rejected. If True, deleting the relaxations will be allowed, which is generally useful for testing when there is no reason for results to be persisted.

Raises:

• RateLimitExceededException – If the call was rejected because a server side rate limit was breached.

• NonRetryableRequestException – If the call was rejected and a retry is not expected to succeed.

• RequestException – For all other errors when making the request; it is possible, though not guaranteed, that a retry could succeed.

Returns:

IDs of the relaxations.

async get_adsorbate_slab_relaxations_request(system_id: str) → ocpapi.client.models.AdsorbateSlabRelaxationsRequest

Fetches the original relaxations request for the input system.

Parameters:

system_id – The ID of the system to fetch.

Raises:

• RateLimitExceededException – If the call was rejected because a server side rate limit was breached.

• NonRetryableRequestException – If the call was rejected and a retry is not expected to succeed.

• RequestException – For all other errors when making the request; it is possible, though not guaranteed, that a retry could succeed.

Returns:

The original request that was made when submitting relaxations.

async get_adsorbate_slab_relaxations_results(system_id: str, config_ids: list[int] | None = None, fields: list[str] | None = None) → ocpapi.client.models.AdsorbateSlabRelaxationsResults

Fetches relaxation results for the input system.

Parameters:

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

Raises:

• RateLimitExceededException – If the call was rejected because a server side rate limit was breached.

• NonRetryableRequestException – If the call was rejected and a retry is not expected to succeed.

• RequestException – For all other errors when making the request; it is possible, though not guaranteed, that a retry could succeed.

Returns:

The relaxation results for each configuration in the system.

async delete_adsorbate_slab_relaxations(system_id: str) → None

Deletes all relaxation results for the input system.

Parameters:

system_id – The ID of the system to delete.

Raises:

• RateLimitExceededException – If the call was rejected because a server side rate limit was breached.

• NonRetryableRequestException – If the call was rejected and a retry is not expected to succeed.

• RequestException – For all other errors when making the request; it is possible, though not guaranteed, that a retry could succeed.

async _run_request(path: str, method: str, **kwargs) → str

Helper method that runs the input request on a thread so that it doesn’t block the event loop on the calling thread.

Parameters:

• path – The URL path to make the request against.

• method – The HTTP method to use (GET, POST, etc.).

Raises:

• RateLimitExceededException – If the call was rejected because a server side rate limit was breached.

• NonRetryableRequestException – If the call was rejected and a retry is not expected to succeed.

• RequestException – For all other errors when making the request; it is possible, though not guaranteed, that a retry could succeed.

Returns:

The response body from the request as a string.