Tutorial Overview
| Property | Value |
|---|---|
| Difficulty | Intermediate |
| Time | 20-30 minutes |
| Prerequisites | Basic Python, ASE |
| Goal | Find optimal adsorption sites using ML-accelerated relaxations |
The AdsorbML paper showed that pre-trained machine learning potentials were now viable to find and prioritize the best adsorption sites for a given surface. The results were quite impressive, especially if you were willing to do a DFT single-point calculation on the best calculations.
The latest UMA models are now total-energy models, and the results for the adsorption energy are even more impressive (see the paper for details and benchmarks). The AdsorbML package helps you with automated multi-adsorbate placement, and will automatically run calculations using the ML models to find the best sites to sample.
Need to install fairchem-core or get UMA access or getting permissions/401 errors?
Install the necessary packages using pip, uv etc
! pip install fairchem-core fairchem-data-oc fairchem-applications-cattsunamiGet access to any necessary huggingface gated models
Get and login to your Huggingface account
Request access to https://
huggingface .co /facebook /UMA Create a Huggingface token at https://
huggingface .co /settings /tokens/ with the permission “Permissions: Read access to contents of all public gated repos you can access” Add the token as an environment variable using
huggingface-cli loginor by setting the HF_TOKEN environment variable.
# Login using the huggingface-cli utility
! huggingface-cli login
# alternatively,
import os
os.environ['HF_TOKEN'] = 'MY_TOKEN'Define desired adsorbate+slab system¶
from __future__ import annotations
import pandas as pd
from fairchem.data.oc.core import Bulk, Slab, Adsorbate
from ase.build import molecule
co_molecule = molecule("CO")
adsorbate = Adsorbate(adsorbate_atoms=co_molecule, adsorbate_binding_indices=[1]) # 1 corresponds to the carbon atom
# adsorbate = [Adsorbate(adsorbate_atoms=co_molecule, adsorbate_binding_indices=[1]) for _ in range(2)] # 2 COs
bulk_src_id = "mp-30"
bulk = Bulk(bulk_src_id_from_db=bulk_src_id)
slabs = Slab.from_bulk_get_specific_millers(bulk=bulk, specific_millers=(1, 1, 1))
# There may be multiple slabs with this miller index.
# For demonstrative purposes we will take the first entry.
slab = slabs[0]Warp DeprecationWarning: The symbol `warp.vec` will soon be removed from the public API. Use `warp.types.vector` instead.
Downloading /home/runner/work/_tool/Python/3.12.13/x64/lib/python3.12/site-packages/fairchem/data/oc/databases/pkls/bulks.pkl...
/home/runner/work/_tool/Python/3.12.13/x64/lib/python3.12/site-packages/fairchem/data/oc/core/bulk.py:66: UserWarning: Loading data from a pickle file. Pickle files can execute arbitrary code and should only be loaded from trusted sources. Consider migrating to a safer format such as Parquet, CSV, or JSON.
bulk_db = safe_pickle_load(fp)
Run heuristic/random adsorbate placement and ML relaxations¶
Now that we’ve defined the bulk, slab, and adsorbates of interest, we can quickly use the pre-trained UMA model as a calculator and the helper script fairchem.core.components.calculate.recipes.adsorbml.run_adsorbml. More details on the automated pipeline can be found at src
from ase.optimize import LBFGS
from fairchem.core import FAIRChemCalculator, pretrained_mlip
from fairchem.core.components.calculate.recipes.adsorbml import run_adsorbml
predictor = pretrained_mlip.get_predict_unit("uma-s-1p2")
calc = FAIRChemCalculator(predictor, task_name="oc20")
outputs = run_adsorbml(
slab=slab,
adsorbate=adsorbate,
calculator=calc,
optimizer_cls=LBFGS,
fmax=0.02,
steps=20, # Increase to 200 for practical application, 20 is used for demonstrations
num_placements=10, # Increase to 100 for practical application, 10 is used for demonstrations
reference_ml_energies=True, # True if using a total energy model (i.e. UMA)
relaxed_slab_atoms=None,
place_on_relaxed_slab=False,
)WARNING:root:device was not explicitly set, using device='cuda'.
Step Time Energy fmax
LBFGS: 0 18:53:12 -300.206729 0.046073
LBFGS: 1 18:53:12 -300.207207 0.044108
LBFGS: 2 18:53:13 -300.212885 0.005266
Step Time Energy fmax
LBFGS: 0 18:53:14 -314.854282 1.556091
LBFGS: 1 18:53:14 -314.868859 2.154185
LBFGS: 2 18:53:15 -314.920343 1.326128
LBFGS: 3 18:53:15 -315.083094 1.175546
LBFGS: 4 18:53:16 -315.102426 0.692285
LBFGS: 5 18:53:16 -315.114037 0.336518
LBFGS: 6 18:53:17 -315.118447 0.347920
LBFGS: 7 18:53:18 -315.123722 0.469725
LBFGS: 8 18:53:18 -315.135303 0.739685
LBFGS: 9 18:53:19 -315.141058 0.442787
LBFGS: 10 18:53:19 -315.143256 0.107361
LBFGS: 11 18:53:20 -315.143595 0.114623
LBFGS: 12 18:53:20 -315.144384 0.151889
LBFGS: 13 18:53:21 -315.145762 0.185178
LBFGS: 14 18:53:21 -315.147503 0.193425
LBFGS: 15 18:53:22 -315.148853 0.132313
LBFGS: 16 18:53:22 -315.149504 0.037846
LBFGS: 17 18:53:23 -315.149763 0.036323
LBFGS: 18 18:53:23 -315.150102 0.059608
LBFGS: 19 18:53:24 -315.150627 0.069901
LBFGS: 20 18:53:25 -315.151063 0.040912
Step Time Energy fmax
LBFGS: 0 18:53:25 -314.795049 1.856075
LBFGS: 1 18:53:26 -314.797503 2.532072
LBFGS: 2 18:53:26 -314.843218 1.027853
LBFGS: 3 18:53:27 -314.913804 1.585635
LBFGS: 4 18:53:27 -315.037368 1.523216
LBFGS: 5 18:53:28 -315.055760 0.607393
LBFGS: 6 18:53:28 -315.072534 0.976535
LBFGS: 7 18:53:29 -315.080977 1.047900
LBFGS: 8 18:53:29 -315.094356 1.440245
LBFGS: 9 18:53:30 -315.112543 1.021003
LBFGS: 10 18:53:30 -315.124567 0.261575
LBFGS: 11 18:53:31 -315.127310 0.204784
LBFGS: 12 18:53:32 -315.127997 0.200209
LBFGS: 13 18:53:32 -315.128526 0.145409
LBFGS: 14 18:53:33 -315.129976 0.066404
LBFGS: 15 18:53:33 -315.130757 0.069179
LBFGS: 16 18:53:34 -315.131163 0.054437
LBFGS: 17 18:53:34 -315.131316 0.046512
LBFGS: 18 18:53:35 -315.131662 0.043728
LBFGS: 19 18:53:35 -315.132133 0.058951
LBFGS: 20 18:53:36 -315.132653 0.062612
Step Time Energy fmax
LBFGS: 0 18:53:36 -314.823335 2.159222
LBFGS: 1 18:53:37 -314.818336 2.916067
LBFGS: 2 18:53:37 -314.871535 1.014592
LBFGS: 3 18:53:38 -314.914631 1.245860
LBFGS: 4 18:53:38 -315.014811 2.114391
LBFGS: 5 18:53:39 -315.022244 1.194785
LBFGS: 6 18:53:39 -315.053258 0.564590
LBFGS: 7 18:53:40 -315.058968 0.286270
LBFGS: 8 18:53:40 -315.068865 0.843532
LBFGS: 9 18:53:41 -315.074465 0.941921
LBFGS: 10 18:53:41 -315.088917 0.744428
LBFGS: 11 18:53:42 -315.093512 0.276269
LBFGS: 12 18:53:42 -315.095783 0.112960
LBFGS: 13 18:53:42 -315.097093 0.174557
LBFGS: 14 18:53:43 -315.098814 0.209562
LBFGS: 15 18:53:43 -315.100601 0.221571
LBFGS: 16 18:53:44 -315.101804 0.153622
LBFGS: 17 18:53:44 -315.102398 0.060264
LBFGS: 18 18:53:45 -315.102639 0.056561
LBFGS: 19 18:53:46 -315.102900 0.091632
LBFGS: 20 18:53:46 -315.103362 0.121491
Step Time Energy fmax
LBFGS: 0 18:53:47 -314.856635 2.197804
LBFGS: 1 18:53:47 -314.852499 2.998370
LBFGS: 2 18:53:48 -314.907133 1.086294
LBFGS: 3 18:53:48 -314.952237 1.270158
LBFGS: 4 18:53:49 -315.034765 2.249470
LBFGS: 5 18:53:49 -315.058645 0.893996
LBFGS: 6 18:53:50 -315.070130 0.337406
LBFGS: 7 18:53:51 -315.072813 0.247097
LBFGS: 8 18:53:51 -315.077460 0.613065
LBFGS: 9 18:53:52 -315.083175 0.816654
LBFGS: 10 18:53:52 -315.088542 0.668638
LBFGS: 11 18:53:53 -315.092047 0.222222
LBFGS: 12 18:53:53 -315.093185 0.156444
LBFGS: 13 18:53:54 -315.094456 0.302820
LBFGS: 14 18:53:54 -315.096742 0.396060
LBFGS: 15 18:53:55 -315.098493 0.295251
LBFGS: 16 18:53:56 -315.099315 0.137076
LBFGS: 17 18:53:56 -315.099710 0.067248
LBFGS: 18 18:53:57 -315.100046 0.136540
LBFGS: 19 18:53:57 -315.100641 0.206963
LBFGS: 20 18:53:58 -315.101278 0.188590
Step Time Energy fmax
LBFGS: 0 18:53:58 -314.855336 2.229029
LBFGS: 1 18:53:59 -314.850539 3.030823
LBFGS: 2 18:53:59 -314.906149 1.087605
LBFGS: 3 18:54:00 -314.950381 1.256732
LBFGS: 4 18:54:00 -315.033647 2.260729
LBFGS: 5 18:54:01 -315.057827 0.917103
LBFGS: 6 18:54:02 -315.070120 0.365084
LBFGS: 7 18:54:02 -315.072924 0.228867
LBFGS: 8 18:54:03 -315.077458 0.594213
LBFGS: 9 18:54:03 -315.083017 0.799243
LBFGS: 10 18:54:04 -315.088269 0.658293
LBFGS: 11 18:54:04 -315.091598 0.225024
LBFGS: 12 18:54:05 -315.092623 0.154785
LBFGS: 13 18:54:06 -315.093735 0.301178
LBFGS: 14 18:54:06 -315.095838 0.413579
LBFGS: 15 18:54:07 -315.097563 0.329451
LBFGS: 16 18:54:07 -315.098447 0.155831
LBFGS: 17 18:54:08 -315.098907 0.078044
LBFGS: 18 18:54:08 -315.099378 0.173327
LBFGS: 19 18:54:09 -315.100167 0.265076
LBFGS: 20 18:54:09 -315.101066 0.252713
Step Time Energy fmax
LBFGS: 0 18:54:10 -314.812930 2.422293
LBFGS: 1 18:54:10 -314.797212 3.183495
LBFGS: 2 18:54:11 -314.857500 0.945520
LBFGS: 3 18:54:11 -314.883072 0.990616
LBFGS: 4 18:54:12 -314.967110 1.962568
LBFGS: 5 18:54:13 -314.848492 3.634282
LBFGS: 6 18:54:13 -315.018382 1.196382
LBFGS: 7 18:54:14 -315.039451 0.620007
LBFGS: 8 18:54:14 -315.052062 1.037192
LBFGS: 9 18:54:15 -315.059618 0.474314
LBFGS: 10 18:54:15 -315.067399 0.365169
LBFGS: 11 18:54:16 -315.085048 0.331044
LBFGS: 12 18:54:16 -315.088897 0.425138
LBFGS: 13 18:54:17 -315.092115 0.344948
LBFGS: 14 18:54:18 -315.095462 0.114437
LBFGS: 15 18:54:18 -315.096789 0.190337
LBFGS: 16 18:54:18 -315.098646 0.308433
LBFGS: 17 18:54:19 -315.101166 0.335137
LBFGS: 18 18:54:20 -315.103045 0.221610
LBFGS: 19 18:54:20 -315.104155 0.108197
LBFGS: 20 18:54:21 -315.104859 0.103234
Step Time Energy fmax
LBFGS: 0 18:54:21 -314.782605 1.690422
LBFGS: 1 18:54:22 -314.789807 2.287014
LBFGS: 2 18:54:22 -314.834741 1.066046
LBFGS: 3 18:54:23 -314.955310 1.840018
LBFGS: 4 18:54:23 -314.942483 2.482832
LBFGS: 5 18:54:24 -315.041931 1.212979
LBFGS: 6 18:54:25 -315.069475 0.612550
LBFGS: 7 18:54:25 -315.083979 1.204165
LBFGS: 8 18:54:26 -315.092935 0.798634
LBFGS: 9 18:54:26 -315.112877 0.409608
LBFGS: 10 18:54:27 -315.128470 0.557558
LBFGS: 11 18:54:27 -315.133178 0.528914
LBFGS: 12 18:54:28 -315.137245 0.182277
LBFGS: 13 18:54:28 -315.138164 0.091303
LBFGS: 14 18:54:29 -315.138466 0.095195
LBFGS: 15 18:54:29 -315.139133 0.104104
LBFGS: 16 18:54:30 -315.139989 0.106335
LBFGS: 17 18:54:30 -315.140717 0.078089
LBFGS: 18 18:54:31 -315.141037 0.041542
LBFGS: 19 18:54:31 -315.141213 0.046026
LBFGS: 20 18:54:31 -315.141474 0.070144
Step Time Energy fmax
LBFGS: 0 18:54:32 -314.750883 1.789547
LBFGS: 1 18:54:32 -314.751728 2.432862
LBFGS: 2 18:54:33 -314.794931 0.924950
LBFGS: 3 18:54:34 -314.857468 1.467674
LBFGS: 4 18:54:34 -315.021729 1.024035
LBFGS: 5 18:54:35 -315.039276 0.672659
LBFGS: 6 18:54:35 -315.071765 1.523055
LBFGS: 7 18:54:36 -315.081591 1.175161
LBFGS: 8 18:54:36 -315.103264 1.631011
LBFGS: 9 18:54:37 -315.123298 0.470851
LBFGS: 10 18:54:37 -315.131797 0.229288
LBFGS: 11 18:54:38 -315.133072 0.074555
LBFGS: 12 18:54:39 -315.133632 0.068919
LBFGS: 13 18:54:39 -315.134465 0.131627
LBFGS: 14 18:54:40 -315.135436 0.123151
LBFGS: 15 18:54:40 -315.136170 0.100182
LBFGS: 16 18:54:41 -315.136462 0.042927
LBFGS: 17 18:54:41 -315.136610 0.041368
LBFGS: 18 18:54:42 -315.136855 0.064816
LBFGS: 19 18:54:42 -315.137250 0.083499
LBFGS: 20 18:54:43 -315.137632 0.059162
Step Time Energy fmax
LBFGS: 0 18:54:44 -314.789224 2.054604
LBFGS: 1 18:54:44 -314.783594 2.789832
LBFGS: 2 18:54:45 -314.832318 0.938512
LBFGS: 3 18:54:45 -314.871033 1.193900
LBFGS: 4 18:54:46 -314.986550 1.989097
LBFGS: 5 18:54:46 -314.875222 3.273258
LBFGS: 6 18:54:47 -315.024401 0.849970
LBFGS: 7 18:54:47 -315.037328 0.423752
LBFGS: 8 18:54:48 -315.052225 1.364152
LBFGS: 9 18:54:48 -315.060591 1.003066
LBFGS: 10 18:54:49 -315.087078 0.478905
LBFGS: 11 18:54:49 -315.097306 0.597841
LBFGS: 12 18:54:50 -315.103308 0.409858
LBFGS: 13 18:54:50 -315.109192 0.148027
LBFGS: 14 18:54:51 -315.111224 0.140438
LBFGS: 15 18:54:52 -315.112350 0.236679
LBFGS: 16 18:54:52 -315.113989 0.170471
LBFGS: 17 18:54:53 -315.115851 0.252736
LBFGS: 18 18:54:53 -315.116932 0.095452
LBFGS: 19 18:54:54 -315.117294 0.048244
LBFGS: 20 18:54:54 -315.117507 0.069056
Step Time Energy fmax
LBFGS: 0 18:54:55 -314.931711 2.799720
LBFGS: 1 18:54:55 -314.909428 3.574821
LBFGS: 2 18:54:56 -314.986486 1.046463
LBFGS: 3 18:54:56 -315.011022 0.854832
LBFGS: 4 18:54:57 -315.062248 1.739463
LBFGS: 5 18:54:58 -315.105539 1.138611
LBFGS: 6 18:54:58 -315.113829 0.476144
LBFGS: 7 18:54:59 -315.118093 0.280620
LBFGS: 8 18:54:59 -315.120658 0.488843
LBFGS: 9 18:55:00 -315.126362 0.732511
LBFGS: 10 18:55:00 -315.130809 0.639011
LBFGS: 11 18:55:01 -315.134409 0.268401
LBFGS: 12 18:55:01 -315.135984 0.148218
LBFGS: 13 18:55:02 -315.137682 0.257583
LBFGS: 14 18:55:02 -315.140915 0.358525
LBFGS: 15 18:55:03 -315.143627 0.252134
LBFGS: 16 18:55:03 -315.144611 0.163627
LBFGS: 17 18:55:04 -315.145185 0.047371
LBFGS: 18 18:55:04 -315.145509 0.086515
LBFGS: 19 18:55:05 -315.145797 0.140933
LBFGS: 20 18:55:06 -315.146322 0.137374
top_candidates = outputs["adslabs"]
global_min_candidate = top_candidates[0]top_candidates = outputs["adslabs"]
pd.DataFrame(top_candidates)Loading...
Write VASP input files¶
If you want to verify the results, you should run VASP. This assumes you have access to VASP pseudopotentials. The default VASP flags (which are equivalent to those used to make OC20) are located in ocdata.utils.vasp. Alternatively, you may pass your own vasp flags to the write_vasp_input_files function as vasp_flags. Note that to run this you need access to the VASP pseudopotentials and need to have those set up in ASE.
import os
from fairchem.data.oc.utils.vasp import write_vasp_input_files
# Grab the 5 systems with the lowest energy
top_5_candidates = top_candidates[:5]
# Write the inputs
for idx, config in enumerate(top_5_candidates):
os.makedirs(f"data/{idx}", exist_ok=True)
write_vasp_input_files(config["atoms"], outdir=f"data/{idx}/")