Skip to content

Commit

Permalink
Documentation fixes
Browse files Browse the repository at this point in the history 
Adds a note to the README about the supported bulks and adsorbates,
fixes some language in documentation throughout the package, and
modifies some docstrings so that they work well with sphinx
documentation generators.
  • Loading branch information
@kjmichel
kjmichel committed Oct 13, 2023
1 parent 2f73665 commit 003e683
Show file tree
Hide file tree
Showing 5 changed files with 344 additions and 192 deletions.
23 changes: 21 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,8 @@ Users will be prompted to select one or more surfaces that should be relaxed.

Input to this function includes:

* The SMILES string of the adsorbate to place
* The Materials Project ID of the bulk structure from which surfaces will be generated
* The name of the adsorbate to place
* A unique ID of the bulk structure from which surfaces will be generated

This function will perform the following steps:

Expand All @@ -68,6 +68,25 @@ This should take 2-10 minutes to finish while tens to hundreds (depending on the
* The predicted force on each atom in the final structure


### Supported bulks and adsorbates

A finite set of bulk materials and adsorbates can be referenced by ID throughout the OCP API. The lists of supported values can be viewed in two ways.

1. Visit the UI at https://open-catalyst.metademolab.com/demo and explore the lists in Step 1 and Step 3.
2. Use the low-level client that ships with this library:
```python
from ocpapi import Client

client = Client()

bulks = await client.get_bulks()
print({b.src_id: b.formula for b in bulks.bulks_supported})

adsorbates = await client.get_adsorbates()
print(adsorbates.adsorbates_supported)
```


### Persisting results

**Results should be saved whenever possible in order to avoid expensive recomputation.**
Expand Down
80 changes: 40 additions & 40 deletions ocpapi/client/client.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -109,15 +109,15 @@ async def get_models(self) -> Models:
Fetch the list of models that are supported in the API.
Raises:
RateLimitExceededException if the call was rejected because a
RateLimitExceededException: If the call was rejected because a
server side rate limit was breached.
NonRetryableRequestException if the call was rejected and a retry
NonRetryableRequestException: If the call was rejected and a retry
is not expected to succeed.
RequestException for all other errors when making the request; it
RequestException: For all other errors when making the request; it
is possible, though not guaranteed, that a retry could succeed.
Returns:
Models
The models that are supported in the API.
"""
response: str = await self._run_request(
path="ocp/models",
Expand All @@ -130,15 +130,15 @@ async def get_bulks(self) -> Bulks:
Fetch the list of bulk materials that are supported in the API.
Raises:
RateLimitExceededException if the call was rejected because a
RateLimitExceededException: If the call was rejected because a
server side rate limit was breached.
NonRetryableRequestException if the call was rejected and a retry
NonRetryableRequestException: If the call was rejected and a retry
is not expected to succeed.
RequestException for all other errors when making the request; it
RequestException: For all other errors when making the request; it
is possible, though not guaranteed, that a retry could succeed.
Returns:
Bulks
The bulks that are supported throughout the API.
"""
response: str = await self._run_request(
path="ocp/bulks",
Expand All @@ -151,15 +151,15 @@ async def get_adsorbates(self) -> Adsorbates:
Fetch the list of adsorbates that are supported in the API.
Raises:
RateLimitExceededException if the call was rejected because a
RateLimitExceededException: If the call was rejected because a
server side rate limit was breached.
NonRetryableRequestException if the call was rejected and a retry
NonRetryableRequestException: If the call was rejected and a retry
is not expected to succeed.
RequestException for all other errors when making the request; it
RequestException: For all other errors when making the request; it
is possible, though not guaranteed, that a retry could succeed.
Returns:
Adsorbates
The adsorbates that are supported throughout the API.
"""
response: str = await self._run_request(
path="ocp/adsorbates",
Expand All @@ -176,15 +176,15 @@ async def get_slabs(self, bulk: Union[str, Bulk]) -> Slabs:
instance to use.
Raises:
RateLimitExceededException if the call was rejected because a
RateLimitExceededException: If the call was rejected because a
server side rate limit was breached.
NonRetryableRequestException if the call was rejected and a retry
NonRetryableRequestException: If the call was rejected and a retry
is not expected to succeed.
RequestException for all other errors when making the request; it
RequestException: For all other errors when making the request; it
is possible, though not guaranteed, that a retry could succeed.
Returns:
Slabs
Slabs for each of the unique surfaces of the material.
"""
response: str = await self._run_request(
path="ocp/slabs",
Expand All @@ -204,20 +204,20 @@ async def get_adsorbate_slab_configs(
input slab.
Args:
adsorbate: SMILES string describing the adsorbate to place.
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
RateLimitExceededException: If the call was rejected because a
server side rate limit was breached.
NonRetryableRequestException if the call was rejected and a retry
NonRetryableRequestException: If the call was rejected and a retry
is not expected to succeed.
RequestException for all other errors when making the request; it
RequestException: For all other errors when making the request; it
is possible, though not guaranteed, that a retry could succeed.
Returns:
AdsorbateSlabConfigs
Configurations for each adsorbate binding site on the slab.
"""
response: str = await self._run_request(
path="ocp/adsorbate-slab-configs",
Expand Down Expand Up @@ -248,7 +248,7 @@ async def submit_adsorbate_slab_relaxations(
that is returned from this method.
Args:
adsorbate: SMILES string describing the adsorbate being simulated.
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.
Expand All @@ -262,15 +262,15 @@ async def submit_adsorbate_slab_relaxations(
testing when there is no reason for results to be persisted.
Raises:
RateLimitExceededException if the call was rejected because a
RateLimitExceededException: If the call was rejected because a
server side rate limit was breached.
NonRetryableRequestException if the call was rejected and a retry
NonRetryableRequestException: If the call was rejected and a retry
is not expected to succeed.
RequestException for all other errors when making the request; it
RequestException: For all other errors when making the request; it
is possible, though not guaranteed, that a retry could succeed.
Returns:
AdsorbateSlabRelaxationsSystem
IDs of the relaxations.
"""
response: str = await self._run_request(
path="ocp/adsorbate-slab-relaxations",
Expand Down Expand Up @@ -299,15 +299,15 @@ async def get_adsorbate_slab_relaxations_request(
system_id: The ID of the system to fetch.
Raises:
RateLimitExceededException if the call was rejected because a
RateLimitExceededException: If the call was rejected because a
server side rate limit was breached.
NonRetryableRequestException if the call was rejected and a retry
NonRetryableRequestException: If the call was rejected and a retry
is not expected to succeed.
RequestException for all other errors when making the request; it
RequestException: For all other errors when making the request; it
is possible, though not guaranteed, that a retry could succeed.
Returns:
AdsorbateSlabRelaxationsRequest
The original request that was made when submitting relaxations.
"""
response: str = await self._run_request(
path=f"ocp/adsorbate-slab-relaxations/{system_id}",
Expand All @@ -332,15 +332,15 @@ async def get_adsorbate_slab_relaxations_results(
configuration to fetch. Otherwise all fields are returned.
Raises:
RateLimitExceededException if the call was rejected because a
RateLimitExceededException: If the call was rejected because a
server side rate limit was breached.
NonRetryableRequestException if the call was rejected and a retry
NonRetryableRequestException: If the call was rejected and a retry
is not expected to succeed.
RequestException for all other errors when making the request; it
RequestException: For all other errors when making the request; it
is possible, though not guaranteed, that a retry could succeed.
Returns:
AdsorbateSlabRelaxationsResults
The relaxation results for each configuration in the system.
"""
params: Dict[str, Any] = {}
if fields:
Expand All @@ -362,11 +362,11 @@ async def delete_adsorbate_slab_relaxations(self, system_id: str) -> None:
system_id: The ID of the system to delete.
Raises:
RateLimitExceededException if the call was rejected because a
RateLimitExceededException: If the call was rejected because a
server side rate limit was breached.
NonRetryableRequestException if the call was rejected and a retry
NonRetryableRequestException: If the call was rejected and a retry
is not expected to succeed.
RequestException for all other errors when making the request; it
RequestException: For all other errors when making the request; it
is possible, though not guaranteed, that a retry could succeed.
"""
await self._run_request(
Expand All @@ -384,11 +384,11 @@ async def _run_request(self, path: str, method: str, **kwargs) -> str:
method: The HTTP method to use (GET, POST, etc.).
Raises:
RateLimitExceededException if the call was rejected because a
RateLimitExceededException: If the call was rejected because a
server side rate limit was breached.
NonRetryableRequestException if the call was rejected and a retry
NonRetryableRequestException: If the call was rejected and a retry
is not expected to succeed.
RequestException for all other errors when making the request; it
RequestException: For all other errors when making the request; it
is possible, though not guaranteed, that a retry could succeed.
Returns:
Expand Down
Loading

0 comments on commit 003e683

Please sign in to comment.