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 06:37:24 -300.206728 0.046073
LBFGS: 1 06:37:24 -300.207207 0.044109
LBFGS: 2 06:37:25 -300.212886 0.005257
Step Time Energy fmax
LBFGS: 0 06:37:26 -314.863503 1.565261
LBFGS: 1 06:37:27 -314.877971 2.189862
LBFGS: 2 06:37:27 -314.929427 1.335284
LBFGS: 3 06:37:28 -315.089924 1.452584
LBFGS: 4 06:37:28 -315.108186 0.622928
LBFGS: 5 06:37:29 -315.116609 0.280766
LBFGS: 6 06:37:30 -315.119875 0.294298
LBFGS: 7 06:37:30 -315.124882 0.431739
LBFGS: 8 06:37:31 -315.133514 0.614152
LBFGS: 9 06:37:32 -315.138854 0.394160
LBFGS: 10 06:37:32 -315.140805 0.097896
LBFGS: 11 06:37:33 -315.141149 0.131464
LBFGS: 12 06:37:34 -315.142295 0.205865
LBFGS: 13 06:37:34 -315.143884 0.249315
LBFGS: 14 06:37:35 -315.145810 0.227878
LBFGS: 15 06:37:36 -315.147063 0.122497
LBFGS: 16 06:37:36 -315.147576 0.040568
LBFGS: 17 06:37:37 -315.147903 0.051860
LBFGS: 18 06:37:38 -315.148518 0.076729
LBFGS: 19 06:37:38 -315.149135 0.077014
LBFGS: 20 06:37:39 -315.149457 0.030529
Step Time Energy fmax
LBFGS: 0 06:37:40 -314.916208 2.800024
LBFGS: 1 06:37:40 -314.893445 3.561471
LBFGS: 2 06:37:41 -314.969471 1.039453
LBFGS: 3 06:37:42 -314.992901 0.863418
LBFGS: 4 06:37:42 -315.046475 1.800365
LBFGS: 5 06:37:43 -315.103038 1.211528
LBFGS: 6 06:37:43 -315.113030 0.561478
LBFGS: 7 06:37:44 -315.119349 0.343509
LBFGS: 8 06:37:45 -315.122367 0.528587
LBFGS: 9 06:37:45 -315.128869 0.687794
LBFGS: 10 06:37:46 -315.133013 0.483679
LBFGS: 11 06:37:46 -315.135542 0.138828
LBFGS: 12 06:37:47 -315.137149 0.241743
LBFGS: 13 06:37:48 -315.139968 0.453064
LBFGS: 14 06:37:48 -315.144545 0.573734
LBFGS: 15 06:37:49 -315.149124 0.461786
LBFGS: 16 06:37:50 -315.151317 0.189914
LBFGS: 17 06:37:50 -315.152577 0.113325
LBFGS: 18 06:37:51 -315.153675 0.224991
LBFGS: 19 06:37:51 -315.155401 0.355382
LBFGS: 20 06:37:52 -315.157738 0.364089
Step Time Energy fmax
LBFGS: 0 06:37:53 -314.763296 1.805105
LBFGS: 1 06:37:53 -314.764586 2.455956
LBFGS: 2 06:37:54 -314.808440 0.950326
LBFGS: 3 06:37:55 -314.873193 1.495388
LBFGS: 4 06:37:55 -315.025657 1.163683
LBFGS: 5 06:37:56 -315.043048 0.637277
LBFGS: 6 06:37:56 -315.070333 1.231918
LBFGS: 7 06:37:57 -315.080400 1.408449
LBFGS: 8 06:37:58 -315.104668 1.076376
LBFGS: 9 06:37:58 -315.116582 1.403100
LBFGS: 10 06:37:59 -315.128963 0.138444
LBFGS: 11 06:37:59 -315.130439 0.085049
LBFGS: 12 06:38:00 -315.131306 0.076890
LBFGS: 13 06:38:00 -315.132047 0.063009
LBFGS: 14 06:38:01 -315.133447 0.094013
LBFGS: 15 06:38:01 -315.134215 0.087803
LBFGS: 16 06:38:02 -315.134572 0.049242
LBFGS: 17 06:38:03 -315.134728 0.039604
LBFGS: 18 06:38:03 -315.134966 0.051663
LBFGS: 19 06:38:04 -315.135361 0.068372
LBFGS: 20 06:38:04 -315.135770 0.054052
Step Time Energy fmax
LBFGS: 0 06:38:05 -314.866861 2.220352
LBFGS: 1 06:38:06 -314.862469 3.042696
LBFGS: 2 06:38:06 -314.917845 1.107918
LBFGS: 3 06:38:07 -314.962205 1.253192
LBFGS: 4 06:38:07 -315.038729 2.296852
LBFGS: 5 06:38:08 -315.063997 0.984886
LBFGS: 6 06:38:09 -315.073613 0.282315
LBFGS: 7 06:38:09 -315.075446 0.218170
LBFGS: 8 06:38:10 -315.079141 0.536418
LBFGS: 9 06:38:11 -315.084153 0.701848
LBFGS: 10 06:38:11 -315.088373 0.537662
LBFGS: 11 06:38:12 -315.090655 0.184913
LBFGS: 12 06:38:13 -315.091846 0.190773
LBFGS: 13 06:38:13 -315.093454 0.396344
LBFGS: 14 06:38:14 -315.096028 0.516514
LBFGS: 15 06:38:15 -315.098214 0.377594
LBFGS: 16 06:38:15 -315.099178 0.133238
LBFGS: 17 06:38:16 -315.099626 0.092583
LBFGS: 18 06:38:17 -315.100123 0.203406
LBFGS: 19 06:38:17 -315.100896 0.286271
LBFGS: 20 06:38:18 -315.101677 0.246497
Step Time Energy fmax
LBFGS: 0 06:38:19 -314.826849 1.913887
LBFGS: 1 06:38:19 -314.830358 2.630181
LBFGS: 2 06:38:20 -314.879030 1.103464
LBFGS: 3 06:38:21 -314.954079 1.655208
LBFGS: 4 06:38:21 -315.052885 1.750462
LBFGS: 5 06:38:22 -315.070618 0.597026
LBFGS: 6 06:38:22 -315.079429 0.425801
LBFGS: 7 06:38:23 -315.084189 0.774329
LBFGS: 8 06:38:24 -315.093337 1.095938
LBFGS: 9 06:38:24 -315.103775 0.982152
LBFGS: 10 06:38:25 -315.112042 0.315817
LBFGS: 11 06:38:26 -315.113705 0.076477
LBFGS: 12 06:38:26 -315.114382 0.144466
LBFGS: 13 06:38:27 -315.115592 0.214647
LBFGS: 14 06:38:27 -315.116875 0.240476
LBFGS: 15 06:38:28 -315.117911 0.174907
LBFGS: 16 06:38:29 -315.118505 0.082577
LBFGS: 17 06:38:29 -315.118855 0.087541
LBFGS: 18 06:38:30 -315.119356 0.143933
LBFGS: 19 06:38:31 -315.120349 0.215522
LBFGS: 20 06:38:31 -315.121620 0.196718
Step Time Energy fmax
LBFGS: 0 06:38:32 -314.851842 1.981743
LBFGS: 1 06:38:32 -314.854711 2.756767
LBFGS: 2 06:38:33 -314.905252 1.153662
LBFGS: 3 06:38:34 -314.974233 1.622624
LBFGS: 4 06:38:34 -315.057170 2.133789
LBFGS: 5 06:38:35 -315.076446 0.707359
LBFGS: 6 06:38:35 -315.082067 0.317957
LBFGS: 7 06:38:36 -315.084360 0.371273
LBFGS: 8 06:38:37 -315.092302 0.472301
LBFGS: 9 06:38:37 -315.098973 0.418560
LBFGS: 10 06:38:38 -315.102898 0.141620
LBFGS: 11 06:38:39 -315.103800 0.114834
LBFGS: 12 06:38:39 -315.104857 0.217405
LBFGS: 13 06:38:40 -315.106659 0.301017
LBFGS: 14 06:38:41 -315.108455 0.270689
LBFGS: 15 06:38:41 -315.109694 0.150691
LBFGS: 16 06:38:42 -315.110344 0.086757
LBFGS: 17 06:38:43 -315.110995 0.111498
LBFGS: 18 06:38:43 -315.112305 0.195374
LBFGS: 19 06:38:44 -315.114120 0.261478
LBFGS: 20 06:38:44 -315.115617 0.181347
Step Time Energy fmax
LBFGS: 0 06:38:45 -314.781836 1.690654
LBFGS: 1 06:38:46 -314.789061 2.285397
LBFGS: 2 06:38:46 -314.834015 1.065533
LBFGS: 3 06:38:47 -314.955075 1.840420
LBFGS: 4 06:38:48 -314.938157 2.526576
LBFGS: 5 06:38:48 -315.041284 1.219544
LBFGS: 6 06:38:49 -315.069178 0.617947
LBFGS: 7 06:38:50 -315.083784 1.223674
LBFGS: 8 06:38:50 -315.092864 0.794105
LBFGS: 9 06:38:51 -315.111830 0.412962
LBFGS: 10 06:38:52 -315.128466 0.534101
LBFGS: 11 06:38:52 -315.133277 0.539400
LBFGS: 12 06:38:53 -315.137350 0.220389
LBFGS: 13 06:38:53 -315.138418 0.094372
LBFGS: 14 06:38:54 -315.138721 0.093209
LBFGS: 15 06:38:55 -315.139377 0.099921
LBFGS: 16 06:38:55 -315.140227 0.101237
LBFGS: 17 06:38:56 -315.140960 0.075450
LBFGS: 18 06:38:57 -315.141282 0.042114
LBFGS: 19 06:38:57 -315.141452 0.045005
LBFGS: 20 06:38:58 -315.141706 0.066266
Step Time Energy fmax
LBFGS: 0 06:38:58 -314.876035 1.586837
LBFGS: 1 06:38:59 -314.888681 2.276653
LBFGS: 2 06:38:59 -314.937949 1.288270
LBFGS: 3 06:38:59 -315.089271 2.011936
LBFGS: 4 06:39:00 -315.107104 0.569811
LBFGS: 5 06:39:01 -315.110417 0.311919
LBFGS: 6 06:39:01 -315.112091 0.301595
LBFGS: 7 06:39:02 -315.117954 0.248256
LBFGS: 8 06:39:02 -315.123262 0.234828
LBFGS: 9 06:39:03 -315.126474 0.132931
LBFGS: 10 06:39:04 -315.127281 0.120038
LBFGS: 11 06:39:04 -315.128199 0.177749
LBFGS: 12 06:39:05 -315.129903 0.233733
LBFGS: 13 06:39:06 -315.132148 0.229375
LBFGS: 14 06:39:06 -315.134294 0.165284
LBFGS: 15 06:39:07 -315.135560 0.080238
LBFGS: 16 06:39:08 -315.136160 0.066187
LBFGS: 17 06:39:08 -315.136935 0.096593
LBFGS: 18 06:39:09 -315.138142 0.111119
LBFGS: 19 06:39:10 -315.139072 0.068922
LBFGS: 20 06:39:10 -315.139383 0.035790
Step Time Energy fmax
LBFGS: 0 06:39:11 -314.836441 1.764710
LBFGS: 1 06:39:12 -314.845008 2.443023
LBFGS: 2 06:39:12 -314.893459 1.186402
LBFGS: 3 06:39:13 -315.011852 1.977732
LBFGS: 4 06:39:13 -315.063375 1.200141
LBFGS: 5 06:39:14 -315.085954 0.703954
LBFGS: 6 06:39:15 -315.092485 0.313336
LBFGS: 7 06:39:15 -315.098685 0.587633
LBFGS: 8 06:39:16 -315.104092 0.792746
LBFGS: 9 06:39:17 -315.114508 0.893931
LBFGS: 10 06:39:17 -315.120624 0.505202
LBFGS: 11 06:39:18 -315.122778 0.101097
LBFGS: 12 06:39:19 -315.123256 0.147589
LBFGS: 13 06:39:19 -315.124301 0.198216
LBFGS: 14 06:39:20 -315.125516 0.218176
LBFGS: 15 06:39:21 -315.126865 0.190198
LBFGS: 16 06:39:21 -315.127786 0.109358
LBFGS: 17 06:39:22 -315.128341 0.073546
LBFGS: 18 06:39:22 -315.128874 0.118811
LBFGS: 19 06:39:23 -315.129947 0.179401
LBFGS: 20 06:39:24 -315.131302 0.170573
Step Time Energy fmax
LBFGS: 0 06:39:24 -314.834403 2.142809
LBFGS: 1 06:39:25 -314.830626 2.905369
LBFGS: 2 06:39:26 -314.883375 1.040639
LBFGS: 3 06:39:26 -314.929291 1.289909
LBFGS: 4 06:39:27 -315.025671 2.149107
LBFGS: 5 06:39:27 -315.041800 0.932675
LBFGS: 6 06:39:28 -315.061978 0.445063
LBFGS: 7 06:39:29 -315.066556 0.259294
LBFGS: 8 06:39:29 -315.075361 0.831730
LBFGS: 9 06:39:30 -315.081104 0.961644
LBFGS: 10 06:39:31 -315.091301 0.757280
LBFGS: 11 06:39:31 -315.096014 0.240527
LBFGS: 12 06:39:32 -315.097539 0.133016
LBFGS: 13 06:39:33 -315.098763 0.205339
LBFGS: 14 06:39:33 -315.100678 0.247707
LBFGS: 15 06:39:34 -315.102421 0.222180
LBFGS: 16 06:39:34 -315.103499 0.153015
LBFGS: 17 06:39:35 -315.104044 0.051245
LBFGS: 18 06:39:36 -315.104312 0.069405
LBFGS: 19 06:39:36 -315.104670 0.118973
LBFGS: 20 06:39:37 -315.105221 0.134569
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}/")