| 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]Downloading /home/runner/work/_tool/Python/3.12.16/x64/lib/python3.12/site-packages/fairchem/data/oc/databases/pkls/bulks.pkl...
/home/runner/work/_tool/Python/3.12.16/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:UMA Nitro cannot serve this request: nitro mode supports only CUDA compute capability 8.x-12.x, not 7.5.
WARNING:root:Now running with nitro=False, execution_mode='umas_fast_gpu' (TF32).
WARNING:root:Running in a reduced-precision mode: some values, such as higher-order derivatives and phonon calculations, will be less accurate. For standard FP32 precision, use inference_settings='high-precision'.
WARNING:root:Model is being compiled. This might take a while the first time.
WARNING:root:Running (unknown commit) with inference settings: multigpu
W1117 18:36:08.478000 14142 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 18:36:50 -300.270010 0.049535
LBFGS: 1 18:36:50 -300.270559 0.047283
LBFGS: 2 18:36:50 -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.
WARNING:root:Now running with merge_mole=False, compile=False, execution_mode='general' (TF32).
Step Time Energy fmax
LBFGS: 0 18:36:55 -314.863442 2.159748
LBFGS: 1 18:36:55 -314.856538 2.914538
LBFGS: 2 18:36:55 -314.909280 0.978586
LBFGS: 3 18:36:55 -314.948510 1.204130
LBFGS: 4 18:36:56 -315.058102 2.031402
LBFGS: 5 18:36:56 -315.004368 2.164814
LBFGS: 6 18:36:56 -315.097346 0.777412
LBFGS: 7 18:36:56 -315.107879 0.367360
LBFGS: 8 18:36:56 -315.120830 1.084879
LBFGS: 9 18:36:56 -315.127967 0.974615
LBFGS: 10 18:36:56 -315.154102 0.856723
LBFGS: 11 18:36:57 -315.158886 0.198961
LBFGS: 12 18:36:57 -315.163394 0.175089
LBFGS: 13 18:36:57 -315.166349 0.126108
LBFGS: 14 18:36:57 -315.167379 0.127241
LBFGS: 15 18:36:57 -315.168964 0.162516
LBFGS: 16 18:36:57 -315.170482 0.188264
LBFGS: 17 18:36:57 -315.171281 0.073682
LBFGS: 18 18:36:58 -315.171593 0.040698
LBFGS: 19 18:36:58 -315.171768 0.059042
LBFGS: 20 18:36:58 -315.172042 0.088176
Step Time Energy fmax
LBFGS: 0 18:36:58 -314.901203 1.767007
LBFGS: 1 18:36:58 -314.910140 2.460558
LBFGS: 2 18:36:58 -314.958783 1.223726
LBFGS: 3 18:36:58 -315.081886 2.070115
LBFGS: 4 18:36:59 -315.124091 1.302319
LBFGS: 5 18:36:59 -315.148893 0.696489
LBFGS: 6 18:36:59 -315.155139 0.319442
LBFGS: 7 18:36:59 -315.161489 0.585206
LBFGS: 8 18:36:59 -315.167336 0.818030
LBFGS: 9 18:36:59 -315.178345 0.950870
LBFGS: 10 18:36:59 -315.185400 0.565071
LBFGS: 11 18:36:59 -315.188030 0.091705
LBFGS: 12 18:37:00 -315.188486 0.121068
LBFGS: 13 18:37:00 -315.189337 0.153157
LBFGS: 14 18:37:00 -315.190313 0.167908
LBFGS: 15 18:37:00 -315.191380 0.149032
LBFGS: 16 18:37:00 -315.192092 0.088087
LBFGS: 17 18:37:00 -315.192551 0.068584
LBFGS: 18 18:37:01 -315.193075 0.105175
LBFGS: 19 18:37:01 -315.194053 0.145901
LBFGS: 20 18:37:01 -315.195205 0.117819
Step Time Energy fmax
LBFGS: 0 18:37:01 -314.895586 1.793803
LBFGS: 1 18:37:01 -314.903429 2.488321
LBFGS: 2 18:37:01 -314.951701 1.195949
LBFGS: 3 18:37:01 -315.063676 1.995200
LBFGS: 4 18:37:01 -315.118075 1.438698
LBFGS: 5 18:37:02 -315.142929 0.779471
LBFGS: 6 18:37:02 -315.150621 0.338464
LBFGS: 7 18:37:02 -315.157495 0.630886
LBFGS: 8 18:37:02 -315.163678 0.867988
LBFGS: 9 18:37:02 -315.176021 1.024187
LBFGS: 10 18:37:02 -315.183869 0.619620
LBFGS: 11 18:37:02 -315.187066 0.090320
LBFGS: 12 18:37:03 -315.187586 0.106315
LBFGS: 13 18:37:03 -315.188294 0.131458
LBFGS: 14 18:37:03 -315.189221 0.147280
LBFGS: 15 18:37:03 -315.190232 0.137789
LBFGS: 16 18:37:03 -315.190929 0.088829
LBFGS: 17 18:37:03 -315.191351 0.062721
LBFGS: 18 18:37:03 -315.191787 0.090614
LBFGS: 19 18:37:03 -315.192613 0.129615
LBFGS: 20 18:37:04 -315.193696 0.117838
Step Time Energy fmax
LBFGS: 0 18:37:04 -314.948515 2.474022
LBFGS: 1 18:37:04 -314.937379 3.290307
LBFGS: 2 18:37:04 -315.001810 1.094161
LBFGS: 3 18:37:04 -315.038215 1.110798
LBFGS: 4 18:37:04 -315.113901 2.165216
LBFGS: 5 18:37:04 -315.146796 1.047067
LBFGS: 6 18:37:04 -315.160911 0.550597
LBFGS: 7 18:37:05 -315.165278 0.246091
LBFGS: 8 18:37:05 -315.170612 0.630435
LBFGS: 9 18:37:05 -315.178175 0.971615
LBFGS: 10 18:37:05 -315.187128 1.020578
LBFGS: 11 18:37:05 -315.195550 0.621489
LBFGS: 12 18:37:05 -315.201056 0.254149
LBFGS: 13 18:37:05 -315.204819 0.480982
LBFGS: 14 18:37:06 -315.213645 0.667293
LBFGS: 15 18:37:06 -315.220371 0.497595
LBFGS: 16 18:37:06 -315.224199 0.256534
LBFGS: 17 18:37:06 -315.225728 0.160597
LBFGS: 18 18:37:06 -315.227061 0.271322
LBFGS: 19 18:37:06 -315.228588 0.374799
LBFGS: 20 18:37:07 -315.230321 0.299706
Step Time Energy fmax
LBFGS: 0 18:37:07 -314.931687 2.180877
LBFGS: 1 18:37:07 -314.928584 3.007498
LBFGS: 2 18:37:07 -314.982972 1.130675
LBFGS: 3 18:37:07 -315.031021 1.327726
LBFGS: 4 18:37:07 -315.108955 2.336140
LBFGS: 5 18:37:08 -315.133084 0.949078
LBFGS: 6 18:37:08 -315.142257 0.209265
LBFGS: 7 18:37:08 -315.143984 0.239310
LBFGS: 8 18:37:08 -315.149604 0.623600
LBFGS: 9 18:37:08 -315.154673 0.693499
LBFGS: 10 18:37:08 -315.158570 0.425422
LBFGS: 11 18:37:09 -315.160343 0.123168
LBFGS: 12 18:37:09 -315.161537 0.252792
LBFGS: 13 18:37:09 -315.163588 0.449392
LBFGS: 14 18:37:09 -315.166005 0.458373
LBFGS: 15 18:37:09 -315.167442 0.243652
LBFGS: 16 18:37:09 -315.167993 0.059348
LBFGS: 17 18:37:10 -315.168388 0.137325
LBFGS: 18 18:37:10 -315.168964 0.238168
LBFGS: 19 18:37:10 -315.169701 0.260457
LBFGS: 20 18:37:10 -315.170254 0.155152
Step Time Energy fmax
LBFGS: 0 18:37:11 -314.856536 1.688789
LBFGS: 1 18:37:11 -314.864551 2.305546
LBFGS: 2 18:37:11 -314.910485 1.107743
LBFGS: 3 18:37:11 -315.037998 1.889397
LBFGS: 4 18:37:11 -315.040056 2.084171
LBFGS: 5 18:37:12 -315.114921 1.026613
LBFGS: 6 18:37:12 -315.133707 0.515882
LBFGS: 7 18:37:12 -315.146262 0.922322
LBFGS: 8 18:37:12 -315.153792 0.846445
LBFGS: 9 18:37:12 -315.183217 1.147643
LBFGS: 10 18:37:12 -315.188695 0.231474
LBFGS: 11 18:37:13 -315.191783 0.176810
LBFGS: 12 18:37:13 -315.194284 0.097151
LBFGS: 13 18:37:13 -315.194683 0.100072
LBFGS: 14 18:37:13 -315.195495 0.193087
LBFGS: 15 18:37:13 -315.196543 0.236254
LBFGS: 16 18:37:13 -315.197392 0.180448
LBFGS: 17 18:37:14 -315.197841 0.078175
LBFGS: 18 18:37:14 -315.198089 0.066115
LBFGS: 19 18:37:14 -315.198392 0.129648
LBFGS: 20 18:37:14 -315.198924 0.181507
Step Time Energy fmax
LBFGS: 0 18:37:14 -314.909329 1.791773
LBFGS: 1 18:37:14 -314.917386 2.513922
LBFGS: 2 18:37:15 -314.966164 1.212689
LBFGS: 3 18:37:15 -315.075212 2.016701
LBFGS: 4 18:37:15 -315.130150 1.550572
LBFGS: 5 18:37:15 -315.149308 0.684960
LBFGS: 6 18:37:15 -315.154506 0.252092
LBFGS: 7 18:37:16 -315.158357 0.463457
LBFGS: 8 18:37:16 -315.164630 0.781447
LBFGS: 9 18:37:16 -315.171786 0.858051
LBFGS: 10 18:37:16 -315.178308 0.495296
LBFGS: 11 18:37:16 -315.180392 0.083953
LBFGS: 12 18:37:16 -315.180937 0.163732
LBFGS: 13 18:37:17 -315.182493 0.277649
LBFGS: 14 18:37:17 -315.183870 0.282162
LBFGS: 15 18:37:17 -315.184994 0.198320
LBFGS: 16 18:37:17 -315.185679 0.079553
LBFGS: 17 18:37:17 -315.186204 0.113110
LBFGS: 18 18:37:18 -315.187021 0.200640
LBFGS: 19 18:37:18 -315.188385 0.259896
LBFGS: 20 18:37:18 -315.189675 0.181161
Step Time Energy fmax
LBFGS: 0 18:37:18 -314.917288 1.694947
LBFGS: 1 18:37:18 -314.928346 2.396358
LBFGS: 2 18:37:19 -314.977751 1.276996
LBFGS: 3 18:37:19 -315.119965 2.181086
LBFGS: 4 18:37:19 -315.147863 0.969455
LBFGS: 5 18:37:19 -315.161322 0.352203
LBFGS: 6 18:37:19 -315.163884 0.227949
LBFGS: 7 18:37:20 -315.169739 0.618662
LBFGS: 8 18:37:20 -315.175467 0.806911
LBFGS: 9 18:37:20 -315.181819 0.659421
LBFGS: 10 18:37:20 -315.185234 0.190573
LBFGS: 11 18:37:20 -315.185896 0.134781
LBFGS: 12 18:37:20 -315.186684 0.261180
LBFGS: 13 18:37:21 -315.188245 0.374737
LBFGS: 14 18:37:21 -315.189802 0.345019
LBFGS: 15 18:37:21 -315.190973 0.200288
LBFGS: 16 18:37:21 -315.191701 0.074128
LBFGS: 17 18:37:21 -315.192354 0.168103
LBFGS: 18 18:37:21 -315.193499 0.285447
LBFGS: 19 18:37:22 -315.194942 0.299173
LBFGS: 20 18:37:22 -315.195877 0.145677
Step Time Energy fmax
LBFGS: 0 18:37:22 -314.934734 2.430164
LBFGS: 1 18:37:22 -314.923257 3.244742
LBFGS: 2 18:37:22 -314.984142 1.070523
LBFGS: 3 18:37:23 -315.017438 1.089598
LBFGS: 4 18:37:23 -315.091620 2.179220
LBFGS: 5 18:37:23 -315.118753 1.078859
LBFGS: 6 18:37:23 -315.135206 0.582577
LBFGS: 7 18:37:23 -315.139440 0.243341
LBFGS: 8 18:37:23 -315.144451 0.594110
LBFGS: 9 18:37:24 -315.149995 0.835237
LBFGS: 10 18:37:24 -315.157239 0.827120
LBFGS: 11 18:37:24 -315.162538 0.435162
LBFGS: 12 18:37:24 -315.164825 0.153861
LBFGS: 13 18:37:24 -315.166195 0.319446
LBFGS: 14 18:37:24 -315.169666 0.535742
LBFGS: 15 18:37:25 -315.172828 0.495175
LBFGS: 16 18:37:25 -315.174841 0.284241
LBFGS: 17 18:37:25 -315.176089 0.147445
LBFGS: 18 18:37:25 -315.177522 0.255744
LBFGS: 19 18:37:25 -315.180146 0.506109
LBFGS: 20 18:37:25 -315.184862 0.751543
Step Time Energy fmax
LBFGS: 0 18:37:26 -315.071646 3.294446
LBFGS: 1 18:37:26 -315.036148 3.968594
LBFGS: 2 18:37:26 -315.135719 1.126523
LBFGS: 3 18:37:26 -315.156462 0.818209
LBFGS: 4 18:37:26 -315.193035 1.505978
LBFGS: 5 18:37:26 -315.246494 1.223714
LBFGS: 6 18:37:27 -315.255181 0.498225
LBFGS: 7 18:37:27 -315.260038 0.263751
LBFGS: 8 18:37:27 -315.262507 0.435178
LBFGS: 9 18:37:27 -315.267760 0.565218
LBFGS: 10 18:37:27 -315.270830 0.388498
LBFGS: 11 18:37:28 -315.272590 0.109754
LBFGS: 12 18:37:28 -315.273770 0.226535
LBFGS: 13 18:37:28 -315.275943 0.427326
LBFGS: 14 18:37:28 -315.278975 0.497407
LBFGS: 15 18:37:28 -315.281459 0.330106
LBFGS: 16 18:37:29 -315.282427 0.096715
LBFGS: 17 18:37:29 -315.282877 0.076439
LBFGS: 18 18:37:29 -315.283364 0.176410
LBFGS: 19 18:37:29 -315.284172 0.254285
LBFGS: 20 18:37:29 -315.284994 0.222660
top_candidates = outputs["adslabs"]
global_min_candidate = top_candidates[0]top_candidates = outputs["adslabs"]
pd.DataFrame(top_candidates)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}/")