ocpapi.client

ocpapi.client#

Submodules#

Exceptions#

`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
`RequestException`	Exception raised any time there is an error while making an API call.

Classes#

`Client`	Exposes each route in the OCP API as a method.
`Adsorbates`	Stores the response from a request to fetch adsorbates supported in the
`AdsorbateSlabConfigs`	Stores the response from a request to fetch placements of a single
`AdsorbateSlabRelaxationResult`	Stores information about a single adsorbate slab configuration, including
`AdsorbateSlabRelaxationsRequest`	Stores the request to submit a new batch of adsorbate slab relaxations.
`AdsorbateSlabRelaxationsResults`	Stores the response from a request for results of adsorbate slab
`AdsorbateSlabRelaxationsSystem`	Stores the response from a request to submit a new batch of adsorbate
`Atoms`	Subset of the fields from an ASE Atoms object that are used within this
`Bulk`	Stores information about a single bulk material.
`Bulks`	Stores the response from a request to fetch bulks supported in the API.
`Model`	Stores information about a single model supported in the API.
`Models`	Stores the response from a request for models supported in the API.
`Slab`	Stores all information about a slab that is returned from the API.
`SlabMetadata`	Stores metadata about a slab that is returned from the API.
`Slabs`	Stores the response from a request to fetch slabs for a bulk structure.
`Status`	Relaxation status of a single adsorbate placement on a slab.

Functions#

get_results_ui_url(→ str | None)

Generates the URL at which results for the input system can be

Package Contents#

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

exception ocpapi.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.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#

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

Bases: Exception

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

class ocpapi.client.Adsorbates#

Bases: _DataModel

Stores the response from a request to fetch adsorbates supported in the API.

adsorbates_supported: List[str]#: List of adsorbates that can be used in the API.

class ocpapi.client.AdsorbateSlabConfigs#

Bases: _DataModel

Stores the response from a request to fetch placements of a single absorbate on a slab.

adsorbate_configs: List[Atoms]#: List of structures, each representing one possible adsorbate placement.

slab: Slab#: The structure of the slab on which the adsorbate is placed.

class ocpapi.client.AdsorbateSlabRelaxationResult#

Bases: _DataModel

Stores information about a single adsorbate slab configuration, including outputs for the model used in relaxations.

The API to fetch relaxation results supports requesting a subset of fields in order to limit the size of response payloads. Optional attributes will be defined only if they are including the response.

config_id: int#: ID of the configuration within the system.

status: Status#: The status of the request for information about this configuration.

system_id: str | None#: The ID of the system in which the configuration was originally submitted.

cell: Tuple[Tuple[float, float, float], Tuple[float, float, float], Tuple[float, float, float]] | None#: 3x3 matrix with unit cell vectors.

pbc: Tuple[bool, bool, bool] | None#: Whether the structure is periodic along the a, b, and c lattice vectors, respectively.

numbers: List[int] | None#: The atomic number of each atom in the unit cell.

positions: List[Tuple[float, float, float]] | None#: The coordinates of each atom in the unit cell, relative to the cartesian frame.

tags: List[int] | None#: Labels for each atom in the unit cell where 0 represents a subsurface atom (fixed during optimization), 1 represents a surface atom, and 2 represents an adsorbate atom.

energy: float | None#: The energy of the configuration.

energy_trajectory: List[float] | None#: The energy of the configuration at each point along the relaxation trajectory.

forces: List[Tuple[float, float, float]] | None#: The forces on each atom in the relaxed structure.

to_ase_atoms() → ase.Atoms#

Creates an ase.Atoms object with the positions, element numbers, etc. populated from values on this object.

The predicted energy and forces will also be copied to the new ase.Atoms object as a SinglePointCalculator (a calculator that stores the results of an already-run simulation).

Returns:: ase.Atoms object with values from this object.

class ocpapi.client.AdsorbateSlabRelaxationsRequest#

Bases: _DataModel

Stores the request to submit a new batch of adsorbate slab relaxations.

adsorbate: str#: Description of the adsorbate.

adsorbate_configs: List[Atoms]#: List of adsorbate placements being relaxed.

bulk: Bulk#: Information about the original bulk structure used to create the slab.

slab: Slab#: The structure of the slab on which adsorbates are placed.

model: str#: The type of the ML model being used during relaxations.

ephemeral: bool | None#: Whether the relaxations can be deleted (assume they cannot be deleted if None).

adsorbate_reaction: str | None#: If possible, an html-formatted string describing the reaction will be added to this field.

class ocpapi.client.AdsorbateSlabRelaxationsResults#

Bases: _DataModel

Stores the response from a request for results of adsorbate slab relaxations.

configs: List[AdsorbateSlabRelaxationResult]#: List of configurations in the system, each representing one placement of an adsorbate on a slab surface.

omitted_config_ids: List[int]#: List of IDs of configurations that were requested but omitted by the server. Results for these IDs can be requested again.

class ocpapi.client.AdsorbateSlabRelaxationsSystem#

Bases: _DataModel

Stores the response from a request to submit a new batch of adsorbate slab relaxations.

system_id: str#: Unique ID for this set of relaxations which can be used to fetch results later.

config_ids: List[int]#: The list of IDs assigned to each of the input adsorbate placements, in the same order in which they were submitted.

class ocpapi.client.Atoms#

Bases: _DataModel

Subset of the fields from an ASE Atoms object that are used within this API.

cell: Tuple[Tuple[float, float, float], Tuple[float, float, float], Tuple[float, float, float]]#: 3x3 matrix with unit cell vectors.

pbc: Tuple[bool, bool, bool]#: Whether the structure is periodic along the a, b, and c lattice vectors, respectively.

numbers: List[int]#: The atomic number of each atom in the unit cell.

positions: List[Tuple[float, float, float]]#: The coordinates of each atom in the unit cell, relative to the cartesian frame.

tags: List[int]#: Labels for each atom in the unit cell where 0 represents a subsurface atom (fixed during optimization), 1 represents a surface atom, and 2 represents an adsorbate atom.

to_ase_atoms() → ase.Atoms#

Creates an ase.Atoms object with the positions, element numbers, etc. populated from values on this object.

Returns:: ase.Atoms object with values from this object.

class ocpapi.client.Bulk#

Bases: _DataModel

Stores information about a single bulk material.

src_id: str#: The ID of the material.

formula: str#: The chemical formula of the material.

elements: List[str]#: The list of elements in the material.

class ocpapi.client.Bulks#

Bases: _DataModel

Stores the response from a request to fetch bulks supported in the API.

bulks_supported: List[Bulk]#: List of bulks that can be used in the API.

class ocpapi.client.Model#

Bases: _DataModel

Stores information about a single model supported in the API.

id: str#: The ID of the model.

class ocpapi.client.Models#

Bases: _DataModel

Stores the response from a request for models supported in the API.

models: List[Model]#: The list of models that are supported.

class ocpapi.client.Slab#

Bases: _DataModel

Stores all information about a slab that is returned from the API.

atoms: Atoms#: The structure of the slab.

metadata: SlabMetadata#: Extra information about the slab.

class ocpapi.client.SlabMetadata#

Bases: _DataModel

Stores metadata about a slab that is returned from the API.

bulk_src_id: str#: The ID of the bulk material from which the slab was derived.

millers: Tuple[int, int, int]#: The Miller indices of the slab relative to bulk structure.

shift: float#: The position along the vector defined by the Miller indices at which a cut was taken to generate the slab surface.

top: bool#: If False, the top and bottom surfaces for this millers/shift pair are distinct and this slab represents the bottom surface.

class ocpapi.client.Slabs#

Bases: _DataModel

Stores the response from a request to fetch slabs for a bulk structure.

slabs: List[Slab]#: The list of slabs that were generated from the input bulk structure.

class ocpapi.client.Status(*args, **kwds)#

Bases: enum.Enum

Relaxation status of a single adsorbate placement on a slab.

NOT_AVAILABLE = 'not_available'#: The configuration exists but the result is not yet available. It is possible that checking again in the future could yield a result.

FAILED_RELAXATION = 'failed_relaxation'#: The relaxation failed for this configuration.

SUCCESS = 'success'#: The relaxation was successful and the requested information about the configuration was returned.

DOES_NOT_EXIST = 'does_not_exist'#: The requested configuration does not exist.

__str__() → str#

ocpapi.client.get_results_ui_url(api_host: str, system_id: str) → str | None#

Generates the URL at which results for the input system can be visualized.

Parameters:

api_host – The API host on which the system was run.
system_id – ID of the system being visualized.

Returns:

The URL at which the input system can be visualized. None if the API host is not recognized.