Package: ocpapi
ocpapiPython library for programmatic use of theOpen Catalyst Demo. Users unfamiliar with the Open Catalyst Demo are encouraged to read more about it before continuing.InstallationEnsure you have Python 3.9.1 or newer, and installocpapiusing:pipinstallocpapiQuickstartThe following examples are used to search for *OH binding sites on Pt surfaces. They use thefind_adsorbate_binding_sitesfunction, which is a high-level workflow on top of other methods included in this library. Once familiar with this routine, users are encouraged to learn about lower-level methods and features that support more advanced use cases.Note about async methodsThis package relies heavily onasyncio. The examples throughout this document can be copied to a python repl launched with:$python-masyncioAlternatively, an async function can be run in a script by wrapping it withasyncio.run():importasynciofromocpapiimportfind_adsorbate_binding_sitesasyncio.run(find_adsorbate_binding_sites(...))Search over all surfacesfromocpapiimportfind_adsorbate_binding_sitesresults=awaitfind_adsorbate_binding_sites(adsorbate="*OH",bulk="mp-126",)Users will be prompted to select one or more surfaces that should be relaxed.Input to this function includes:The name of the adsorbate to placeA unique ID of the bulk structure from which surfaces will be generatedThis function will perform the following steps:Enumerate surfaces of the bulk materialOn each surface, enumerate initial guesses for adorbate binding sitesRun local force-based relaxations of each adsorbate placementIn addition, this handles:Retrying failed calls to the Open Catalyst Demo APIRetrying submission of relaxations when they are rate limitedThis 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 indicesThe initial positions of the adsorbate before relaxationThe final structure after relaxationThe predicted energy of the final structureThe predicted force on each atom in the final structureSupported bulks and adsorbatesA 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.Visit the UI athttps://open-catalyst.metademolab.com/demoand explore the lists in Step 1 and Step 3.Use the low-level client that ships with this library:fromocpapiimportClientclient=Client()bulks=awaitclient.get_bulks()print({b.src_id:b.formulaforbinbulks.bulks_supported})adsorbates=awaitclient.get_adsorbates()print(adsorbates.adsorbates_supported)Persisting resultsResults should be saved whenever possible in order to avoid expensive recomputation.Assumingresultswas generated with thefind_adsorbate_binding_sitesmethod used above, it is anAdsorbateBindingSitesobject. This can be saved to file with:withopen("results.json","w")asf:f.write(results.to_json())Similarly, results can be read back from file to anAdsorbateBindingSitesobject with:fromocpapiimportAdsorbateBindingSiteswithopen("results.json","r")asf:results=AdsorbateBindingSites.from_json(f.read())Viewing results in the web UIRelaxation results can be viewed in a web UI. For example,https://open-catalyst.metademolab.com/results/7eaa0d63-83aa-473f-ac84-423ffd0c67f5shows the results of relaxing *OH on a Pt (1,1,1) surface; the uuid, "7eaa0d63-83aa-473f-ac84-423ffd0c67f5", is referred to as thesystem_id.Extending the examples above, the URLs to visualize the results of relaxations on each Pt surface can be obtained with:urls=[slab.ui_urlforslabinresults.slabs]Advanced usageChanging the model typeThe API currently supports two models:equiformer_v2_31M_s2ef_all_md(default):https://arxiv.org/abs/2306.12059gemnet_oc_base_s2ef_all_md:https://arxiv.org/abs/2204.02782A specific model type can be requested with:fromocpapiimportfind_adsorbate_binding_sitesresults=awaitfind_adsorbate_binding_sites(adsorbate="*OH",bulk="mp-126",model="gemnet_oc_base_s2ef_all_md",)Skip relaxation approval promptsCalls tofind_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_filtercan be set to a function that automatically approves any or all adsorbate/slab (adslab) configurations.Run relaxations for all slabs that are generated:fromocpapiimportfind_adsorbate_binding_sites,keep_all_slabsresults=awaitfind_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:fromocpapiimportfind_adsorbate_binding_sites,keep_slabs_with_miller_indicesresults=awaitfind_adsorbate_binding_sites(adsorbate="*OH",bulk="mp-126",adslab_filter=keep_slabs_with_miller_indices([(1,0,0),(1,1,1)]),)Converting toase.AtomsobjectsImportant! Theto_ase_atoms()method described below will fail with an import error ifaseis not installed.Two classes have support for generatingase.Atomsobjects:ocpapi.Atoms.to_ase_atoms(): Adds unit cell, atomic positions, and other structural information to the returnedase.Atomsobject.ocpapi.AdsorbateSlabRelaxationResult.to_ase_atoms(): Adds the same structure information to thease.Atomsobject. Also adds the predicted forces and energy of the relaxed structure, which can be accessed with thease.Atoms.get_potential_energy()andase.Atoms.get_forces()methods.For example, the following would generate anase.Atomsobject for the first relaxed adsorbate configuration on the first slab generated for *OH binding on Pt:fromocpapiimportfind_adsorbate_binding_sitesresults=awaitfind_adsorbate_binding_sites(adsorbate="*OH",bulk="mp-126",)ase_atoms=results.slabs[0].configs[0].to_ase_atoms()Converting to other structure formatsFrom anase.Atomsobject (see previous section), is is possible towrite to other structure formats. Extending the example above, thease_atomsobject could be written to aVASP POSCAR filewith:fromase.ioimportwritewrite("POSCAR",ase_atoms,"vasp")Licenseocpapiis released under theMIT License.CitingocpapiIf you useocpapiin your research, please consider citing theAdsorbML paper(in addition to the relevant datasets / models used):@article{lan2023adsorbml,title={{AdsorbML}: a leap in efficiency for adsorption energy calculations using generalizable machine learning potentials},author={Lan*, Janice and Palizhati*, Aini and Shuaibi*, Muhammed and Wood*, Brandon M and Wander, Brook and Das, Abhishek and Uyttendaele, Matt and Zitnick, C Lawrence and Ulissi, Zachary W},journal={npj Computational Materials},year={2023},}