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 1.18.0 initialized:
CUDA Toolkit 13.4, Driver 13.1
Devices:
"cpu" : "x86_64"
"cuda:0" : "Tesla T4" (16 GiB, sm_75, mempool enabled)
Kernel cache:
/home/runner/.cache/warp/1.18.0
Downloading /home/runner/work/_tool/Python/3.12.15/x64/lib/python3.12/site-packages/fairchem/data/oc/databases/pkls/bulks.pkl...
/home/runner/work/_tool/Python/3.12.15/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-1p2p1")
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'.
WARNING:root:Model is being compiled this might take a while for the first time
W1007 02:56:47.079000 9374 site-packages/torch/_logging/_internal.py:1345] [0/0] Profiler record function <class 'torch.autograd.profiler.record_function'> will be ignored
Step Time Energy fmax
LBFGS: 0 02:57:42 -300.270009 0.049535
LBFGS: 1 02:57:42 -300.270559 0.047282
LBFGS: 2 02:57:43 -300.276506 0.003902
WARNING:root:The UMA fast path (merge_mole + compile) is only available for fixed composition, task, charge, and spin. This is optimized for MD applications. Falling back to a less optimized version for subsequent evaluations. Reason: 'Compositions differ from merged model'.
Use inference_settings='batch' for heterogeneous batched evaluations.
Step Time Energy fmax
LBFGS: 0 02:57:49 -314.863443 2.159748
LBFGS: 1 02:57:49 -314.856538 2.914538
LBFGS: 2 02:57:50 -314.909279 0.978586
LBFGS: 3 02:57:50 -314.948510 1.204130
LBFGS: 4 02:57:50 -315.058103 2.031401
LBFGS: 5 02:57:51 -315.004366 2.164813
LBFGS: 6 02:57:51 -315.097346 0.777413
LBFGS: 7 02:57:51 -315.107881 0.367277
LBFGS: 8 02:57:51 -315.120833 1.084344
LBFGS: 9 02:57:52 -315.127974 0.974694
LBFGS: 10 02:57:52 -315.154102 0.856865
LBFGS: 11 02:57:52 -315.158887 0.199065
LBFGS: 12 02:57:53 -315.163395 0.175191
LBFGS: 13 02:57:53 -315.166347 0.126114
LBFGS: 14 02:57:53 -315.167378 0.127156
LBFGS: 15 02:57:54 -315.168961 0.162832
LBFGS: 16 02:57:54 -315.170482 0.188226
LBFGS: 17 02:57:54 -315.171285 0.073699
LBFGS: 18 02:57:54 -315.171597 0.040946
LBFGS: 19 02:57:55 -315.171769 0.059233
LBFGS: 20 02:57:55 -315.172043 0.088443
Step Time Energy fmax
LBFGS: 0 02:57:55 -314.901206 1.767008
LBFGS: 1 02:57:55 -314.910138 2.460559
LBFGS: 2 02:57:56 -314.958786 1.223727
LBFGS: 3 02:57:56 -315.081885 2.070113
LBFGS: 4 02:57:56 -315.124091 1.302319
LBFGS: 5 02:57:57 -315.148893 0.696489
LBFGS: 6 02:57:57 -315.155139 0.319442
LBFGS: 7 02:57:57 -315.161489 0.585206
LBFGS: 8 02:57:58 -315.167336 0.818031
LBFGS: 9 02:57:58 -315.178343 0.950871
LBFGS: 10 02:57:58 -315.185398 0.565071
LBFGS: 11 02:57:59 -315.188029 0.091704
LBFGS: 12 02:57:59 -315.188485 0.121068
LBFGS: 13 02:57:59 -315.189338 0.153125
LBFGS: 14 02:57:59 -315.190312 0.167933
LBFGS: 15 02:58:00 -315.191376 0.149290
LBFGS: 16 02:58:00 -315.192091 0.087768
LBFGS: 17 02:58:00 -315.192552 0.068609
LBFGS: 18 02:58:01 -315.193070 0.105022
LBFGS: 19 02:58:01 -315.194054 0.145705
LBFGS: 20 02:58:01 -315.195210 0.117624
Step Time Energy fmax
LBFGS: 0 02:58:01 -314.895586 1.793802
LBFGS: 1 02:58:02 -314.903431 2.488322
LBFGS: 2 02:58:02 -314.951702 1.195948
LBFGS: 3 02:58:02 -315.063676 1.995200
LBFGS: 4 02:58:03 -315.118076 1.438699
LBFGS: 5 02:58:03 -315.142929 0.779462
LBFGS: 6 02:58:03 -315.150624 0.338467
LBFGS: 7 02:58:04 -315.157493 0.630903
LBFGS: 8 02:58:04 -315.163678 0.868138
LBFGS: 9 02:58:04 -315.176023 1.024036
LBFGS: 10 02:58:04 -315.183871 0.619485
LBFGS: 11 02:58:05 -315.187069 0.090240
LBFGS: 12 02:58:05 -315.187585 0.106291
LBFGS: 13 02:58:05 -315.188291 0.131658
LBFGS: 14 02:58:06 -315.189222 0.147275
LBFGS: 15 02:58:06 -315.190231 0.137855
LBFGS: 16 02:58:06 -315.190930 0.089073
LBFGS: 17 02:58:07 -315.191354 0.062921
LBFGS: 18 02:58:07 -315.191788 0.090531
LBFGS: 19 02:58:07 -315.192618 0.129391
LBFGS: 20 02:58:07 -315.193695 0.117677
Step Time Energy fmax
LBFGS: 0 02:58:08 -314.948517 2.474022
LBFGS: 1 02:58:08 -314.937378 3.290308
LBFGS: 2 02:58:08 -315.001810 1.094162
LBFGS: 3 02:58:08 -315.038212 1.110963
LBFGS: 4 02:58:09 -315.113903 2.164810
LBFGS: 5 02:58:09 -315.146795 1.046937
LBFGS: 6 02:58:09 -315.160909 0.550581
LBFGS: 7 02:58:10 -315.165280 0.246066
LBFGS: 8 02:58:10 -315.170612 0.630905
LBFGS: 9 02:58:10 -315.178161 0.971343
LBFGS: 10 02:58:11 -315.187134 1.020465
LBFGS: 11 02:58:11 -315.195547 0.621705
LBFGS: 12 02:58:11 -315.201057 0.254139
LBFGS: 13 02:58:11 -315.204820 0.480980
LBFGS: 14 02:58:12 -315.213642 0.667097
LBFGS: 15 02:58:12 -315.220371 0.497898
LBFGS: 16 02:58:12 -315.224196 0.256557
LBFGS: 17 02:58:13 -315.225731 0.160608
LBFGS: 18 02:58:13 -315.227061 0.271066
LBFGS: 19 02:58:13 -315.228590 0.374666
LBFGS: 20 02:58:13 -315.230318 0.299863
Step Time Energy fmax
LBFGS: 0 02:58:14 -314.931687 2.180877
LBFGS: 1 02:58:14 -314.928586 3.007498
LBFGS: 2 02:58:14 -314.982974 1.130676
LBFGS: 3 02:58:15 -315.031021 1.327725
LBFGS: 4 02:58:15 -315.108958 2.336141
LBFGS: 5 02:58:15 -315.133083 0.949079
LBFGS: 6 02:58:15 -315.142256 0.209266
LBFGS: 7 02:58:16 -315.143983 0.239312
LBFGS: 8 02:58:16 -315.149606 0.623588
LBFGS: 9 02:58:16 -315.154674 0.693498
LBFGS: 10 02:58:16 -315.158570 0.425427
LBFGS: 11 02:58:17 -315.160346 0.123169
LBFGS: 12 02:58:17 -315.161537 0.252783
LBFGS: 13 02:58:17 -315.163591 0.449347
LBFGS: 14 02:58:17 -315.166004 0.458531
LBFGS: 15 02:58:18 -315.167440 0.243782
LBFGS: 16 02:58:18 -315.167995 0.059170
LBFGS: 17 02:58:18 -315.168387 0.137244
LBFGS: 18 02:58:18 -315.168969 0.238220
LBFGS: 19 02:58:19 -315.169701 0.260361
LBFGS: 20 02:58:19 -315.170252 0.155218
Step Time Energy fmax
LBFGS: 0 02:58:19 -314.856536 1.688788
LBFGS: 1 02:58:20 -314.864549 2.305546
LBFGS: 2 02:58:20 -314.910487 1.107743
LBFGS: 3 02:58:20 -315.037999 1.889397
LBFGS: 4 02:58:20 -315.040049 2.084238
LBFGS: 5 02:58:21 -315.114918 1.026774
LBFGS: 6 02:58:21 -315.133708 0.515807
LBFGS: 7 02:58:21 -315.146260 0.921815
LBFGS: 8 02:58:21 -315.153795 0.846468
LBFGS: 9 02:58:21 -315.183214 1.147783
LBFGS: 10 02:58:22 -315.188690 0.231394
LBFGS: 11 02:58:22 -315.191780 0.177450
LBFGS: 12 02:58:22 -315.194284 0.096659
LBFGS: 13 02:58:23 -315.194682 0.099978
LBFGS: 14 02:58:23 -315.195499 0.192763
LBFGS: 15 02:58:23 -315.196545 0.236463
LBFGS: 16 02:58:24 -315.197392 0.179741
LBFGS: 17 02:58:24 -315.197843 0.078086
LBFGS: 18 02:58:24 -315.198092 0.066440
LBFGS: 19 02:58:24 -315.198392 0.129312
LBFGS: 20 02:58:25 -315.198928 0.181669
Step Time Energy fmax
LBFGS: 0 02:58:25 -314.909330 1.791773
LBFGS: 1 02:58:25 -314.917388 2.513921
LBFGS: 2 02:58:25 -314.966165 1.212689
LBFGS: 3 02:58:26 -315.075214 2.016700
LBFGS: 4 02:58:26 -315.130150 1.550572
LBFGS: 5 02:58:26 -315.149308 0.684961
LBFGS: 6 02:58:26 -315.154506 0.252092
LBFGS: 7 02:58:27 -315.158357 0.463457
LBFGS: 8 02:58:27 -315.164630 0.781447
LBFGS: 9 02:58:27 -315.171788 0.858036
LBFGS: 10 02:58:28 -315.178310 0.495171
LBFGS: 11 02:58:28 -315.180393 0.083812
LBFGS: 12 02:58:28 -315.180941 0.163510
LBFGS: 13 02:58:29 -315.182491 0.278454
LBFGS: 14 02:58:29 -315.183866 0.282109
LBFGS: 15 02:58:29 -315.184995 0.198422
LBFGS: 16 02:58:29 -315.185682 0.079513
LBFGS: 17 02:58:30 -315.186206 0.113260
LBFGS: 18 02:58:30 -315.187020 0.199913
LBFGS: 19 02:58:30 -315.188384 0.260106
LBFGS: 20 02:58:31 -315.189672 0.181023
Step Time Energy fmax
LBFGS: 0 02:58:31 -314.917286 1.694947
LBFGS: 1 02:58:31 -314.928345 2.396358
LBFGS: 2 02:58:31 -314.977753 1.276995
LBFGS: 3 02:58:32 -315.119963 2.181086
LBFGS: 4 02:58:32 -315.147865 0.969274
LBFGS: 5 02:58:32 -315.161322 0.352217
LBFGS: 6 02:58:33 -315.163887 0.227910
LBFGS: 7 02:58:33 -315.169742 0.618755
LBFGS: 8 02:58:33 -315.175462 0.806658
LBFGS: 9 02:58:33 -315.181824 0.659315
LBFGS: 10 02:58:34 -315.185233 0.190601
LBFGS: 11 02:58:34 -315.185900 0.134802
LBFGS: 12 02:58:34 -315.186687 0.261227
LBFGS: 13 02:58:35 -315.188247 0.374806
LBFGS: 14 02:58:35 -315.189802 0.345025
LBFGS: 15 02:58:35 -315.190971 0.200283
LBFGS: 16 02:58:36 -315.191699 0.074200
LBFGS: 17 02:58:36 -315.192351 0.167972
LBFGS: 18 02:58:36 -315.193500 0.285694
LBFGS: 19 02:58:36 -315.194938 0.299410
LBFGS: 20 02:58:37 -315.195880 0.145218
Step Time Energy fmax
LBFGS: 0 02:58:37 -314.934734 2.430164
LBFGS: 1 02:58:37 -314.923258 3.244741
LBFGS: 2 02:58:38 -314.984143 1.070523
LBFGS: 3 02:58:38 -315.017437 1.089598
LBFGS: 4 02:58:38 -315.091621 2.179220
LBFGS: 5 02:58:39 -315.118752 1.078858
LBFGS: 6 02:58:39 -315.135206 0.582577
LBFGS: 7 02:58:39 -315.139439 0.243341
LBFGS: 8 02:58:40 -315.144450 0.594110
LBFGS: 9 02:58:40 -315.149993 0.835238
LBFGS: 10 02:58:40 -315.157239 0.827120
LBFGS: 11 02:58:40 -315.162539 0.435163
LBFGS: 12 02:58:41 -315.164826 0.153684
LBFGS: 13 02:58:41 -315.166198 0.319801
LBFGS: 14 02:58:41 -315.169658 0.535395
LBFGS: 15 02:58:42 -315.172829 0.495216
LBFGS: 16 02:58:42 -315.174838 0.284776
LBFGS: 17 02:58:42 -315.176088 0.147458
LBFGS: 18 02:58:43 -315.177520 0.255517
LBFGS: 19 02:58:43 -315.180143 0.506074
LBFGS: 20 02:58:43 -315.184859 0.751410
Step Time Energy fmax
LBFGS: 0 02:58:43 -315.071642 3.294446
LBFGS: 1 02:58:44 -315.036150 3.968594
LBFGS: 2 02:58:44 -315.135720 1.126523
LBFGS: 3 02:58:44 -315.156461 0.818209
LBFGS: 4 02:58:45 -315.193035 1.505978
LBFGS: 5 02:58:45 -315.246493 1.223889
LBFGS: 6 02:58:45 -315.255181 0.498082
LBFGS: 7 02:58:46 -315.260037 0.263618
LBFGS: 8 02:58:46 -315.262507 0.435180
LBFGS: 9 02:58:46 -315.267758 0.565282
LBFGS: 10 02:58:46 -315.270827 0.388818
LBFGS: 11 02:58:47 -315.272595 0.109768
LBFGS: 12 02:58:47 -315.273770 0.226391
LBFGS: 13 02:58:47 -315.275942 0.427168
LBFGS: 14 02:58:47 -315.278972 0.497553
LBFGS: 15 02:58:48 -315.281454 0.330584
LBFGS: 16 02:58:48 -315.282430 0.096581
LBFGS: 17 02:58:48 -315.282874 0.076167
LBFGS: 18 02:58:48 -315.283363 0.176396
LBFGS: 19 02:58:49 -315.284170 0.254452
LBFGS: 20 02:58:49 -315.284992 0.222647
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}/")