Merge pull request #21 from Open-Catalyst-Project/relaxation-choices

Relaxation choices

README.md

@@ -41,6 +41,8 @@ results = await find_adsorbate_binding_sites(
 )
 ```
 
+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
@@ -57,7 +59,7 @@ In addition, this handles:
 * Retrying failed calls to the Open Catalyst Demo API
 * Retrying submission of relaxations when they are rate limited
 
-This should take 5-10 minutes to finish while hundreds of individual adsorbate placements are relaxed over six unique surfaces of Pt. Each of the objects in the returned list includes (among other details):
+This should take 2-10 minutes to finish while tens to hundreds (depending on the number of surfaces that are selected) of individual adsorbate placements are relaxed on unique surfaces of Pt. Each of the objects in the returned list includes (among other details):
 
 * Information about the surface being searched, including its structure and Miller indices
 * The initial positions of the adsorbate before relaxation
@@ -66,24 +68,6 @@ This should take 5-10 minutes to finish while hundreds of individual adsorbate p
 * The predicted force on each atom in the final structure
 
 
-### Search over a subset of Miller indices
-
-```python
-from ocpapi import (
-    find_adsorbate_binding_sites,
-    keep_slabs_with_miller_indices,
-)
-
-results = await find_adsorbate_binding_sites(
-    adsorbate="*OH",
-    bulk="mp-126",
-    slab_filter=keep_slabs_with_miller_indices([(1, 1, 0), (1, 1, 1)])
-)
-```
-
-This example adds the `slab_filter` field, which takes a function that selects out generated surfaces that meet some criteria; in this case, keeping only the surfaces that have Miller indices of (1, 1, 0) or (1, 1, 1).
-
-
 ### Persisting results
 
 **Results should be saved whenever possible in order to avoid expensive recomputation.**
@@ -135,6 +119,32 @@ results = await find_adsorbate_binding_sites(
 )
 ```
 
+### Skip relaxation approval prompts
+
+Calls to `find_adsorbate_binding_sites()` will, by default, show the user all pending relaxations and ask for approval before they are submitted. In order to run the relaxations automatically without manual approval, `adslab_filter` can be set to a function that automatically approves any or all adsorbate/slab (adslab) configurations.
+
+Run relaxations for all slabs that are generated:
+```python
+from ocpapi import find_adsorbate_binding_sites, keep_all_slabs
+
+results = await find_adsorbate_binding_sites(
+    adsorbate="*OH",
+    bulk="mp-126",
+    adslab_filter=keep_all_slabs(),
+)
+```
+
+Run relaxations only for slabs with Miller Indices in the input set:
+```python
+from ocpapi import find_adsorbate_binding_sites, keep_slabs_with_miller_indices
+
+results = await find_adsorbate_binding_sites(
+    adsorbate="*OH",
+    bulk="mp-126",
+    adslab_filter=keep_slabs_with_miller_indices([(1, 0, 0), (1, 1, 1)]),
+)
+```
+
 ### Converting to [ase.Atoms](https://wiki.fysik.dtu.dk/ase/ase/atoms.html) objects
 
 **Important! The `to_ase_atoms()` method described below will fail with an import error if [ase](https://wiki.fysik.dtu.dk/ase) is not installed.**

ocpapi/workflows/__init__.py

@@ -7,9 +7,13 @@
     UnsupportedModelException,
     find_adsorbate_binding_sites,
     get_adsorbate_slab_relaxation_results,
-    keep_slabs_with_miller_indices,
     wait_for_adsorbate_slab_relaxations,
 )
+from .filter import (  # noqa
+    keep_all_slabs,
+    keep_slabs_with_miller_indices,
+    prompt_for_slabs_to_keep,
+)
 from .retry import (  # noqa
     NO_LIMIT,
     NoLimitType,