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]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 14:26:15 -300.206729 0.046073
LBFGS: 1 14:26:15 -300.207207 0.044109
LBFGS: 2 14:26:16 -300.212885 0.005257
Step Time Energy fmax
LBFGS: 0 14:26:17 -314.863503 1.565260
LBFGS: 1 14:26:17 -314.877967 2.189862
LBFGS: 2 14:26:18 -314.929427 1.335284
LBFGS: 3 14:26:18 -315.089923 1.452585
LBFGS: 4 14:26:19 -315.108187 0.622928
LBFGS: 5 14:26:19 -315.116606 0.280766
LBFGS: 6 14:26:20 -315.119875 0.294304
LBFGS: 7 14:26:21 -315.124882 0.431739
LBFGS: 8 14:26:21 -315.133515 0.613985
LBFGS: 9 14:26:22 -315.138860 0.394164
LBFGS: 10 14:26:22 -315.140807 0.097890
LBFGS: 11 14:26:23 -315.141147 0.131279
LBFGS: 12 14:26:24 -315.142293 0.206465
LBFGS: 13 14:26:24 -315.143885 0.249198
LBFGS: 14 14:26:25 -315.145808 0.227656
LBFGS: 15 14:26:25 -315.147064 0.122322
LBFGS: 16 14:26:26 -315.147574 0.040566
LBFGS: 17 14:26:27 -315.147902 0.051376
LBFGS: 18 14:26:27 -315.148518 0.077178
LBFGS: 19 14:26:28 -315.149133 0.076427
LBFGS: 20 14:26:28 -315.149458 0.030511
Step Time Energy fmax
LBFGS: 0 14:26:29 -314.916205 2.800023
LBFGS: 1 14:26:30 -314.893443 3.561471
LBFGS: 2 14:26:30 -314.969474 1.039454
LBFGS: 3 14:26:31 -314.992898 0.863418
LBFGS: 4 14:26:31 -315.046472 1.800364
LBFGS: 5 14:26:32 -315.103039 1.211531
LBFGS: 6 14:26:33 -315.113028 0.561478
LBFGS: 7 14:26:33 -315.119348 0.343509
LBFGS: 8 14:26:34 -315.122366 0.528589
LBFGS: 9 14:26:35 -315.128870 0.687940
LBFGS: 10 14:26:35 -315.133012 0.483685
LBFGS: 11 14:26:36 -315.135537 0.138833
LBFGS: 12 14:26:36 -315.137152 0.241891
LBFGS: 13 14:26:37 -315.139971 0.452875
LBFGS: 14 14:26:37 -315.144549 0.573775
LBFGS: 15 14:26:38 -315.149121 0.461936
LBFGS: 16 14:26:39 -315.151317 0.189609
LBFGS: 17 14:26:39 -315.152578 0.113076
LBFGS: 18 14:26:40 -315.153676 0.225233
LBFGS: 19 14:26:40 -315.155395 0.355410
LBFGS: 20 14:26:41 -315.157738 0.364487
Step Time Energy fmax
LBFGS: 0 14:26:41 -314.763296 1.805104
LBFGS: 1 14:26:42 -314.764586 2.455957
LBFGS: 2 14:26:43 -314.808440 0.950326
LBFGS: 3 14:26:43 -314.873198 1.495390
LBFGS: 4 14:26:44 -315.025660 1.163692
LBFGS: 5 14:26:44 -315.043048 0.637293
LBFGS: 6 14:26:45 -315.070334 1.231348
LBFGS: 7 14:26:46 -315.080395 1.409598
LBFGS: 8 14:26:46 -315.104613 1.078539
LBFGS: 9 14:26:47 -315.116621 1.398246
LBFGS: 10 14:26:47 -315.128955 0.139762
LBFGS: 11 14:26:48 -315.130436 0.085057
LBFGS: 12 14:26:49 -315.131305 0.076932
LBFGS: 13 14:26:49 -315.132041 0.063035
LBFGS: 14 14:26:50 -315.133448 0.094353
LBFGS: 15 14:26:51 -315.134214 0.087881
LBFGS: 16 14:26:51 -315.134571 0.049357
LBFGS: 17 14:26:52 -315.134727 0.039568
LBFGS: 18 14:26:52 -315.134967 0.051612
LBFGS: 19 14:26:53 -315.135356 0.069067
LBFGS: 20 14:26:54 -315.135767 0.054027
Step Time Energy fmax
LBFGS: 0 14:26:54 -314.866863 2.220352
LBFGS: 1 14:26:55 -314.862474 3.042696
LBFGS: 2 14:26:55 -314.917843 1.107918
LBFGS: 3 14:26:56 -314.962205 1.253191
LBFGS: 4 14:26:56 -315.038727 2.296852
LBFGS: 5 14:26:57 -315.063995 0.984886
LBFGS: 6 14:26:58 -315.073614 0.282307
LBFGS: 7 14:26:58 -315.075444 0.218172
LBFGS: 8 14:26:59 -315.079142 0.536246
LBFGS: 9 14:26:59 -315.084150 0.702059
LBFGS: 10 14:27:00 -315.088370 0.537807
LBFGS: 11 14:27:00 -315.090657 0.184599
LBFGS: 12 14:27:01 -315.091848 0.190305
LBFGS: 13 14:27:02 -315.093458 0.396892
LBFGS: 14 14:27:02 -315.096024 0.516512
LBFGS: 15 14:27:03 -315.098213 0.377575
LBFGS: 16 14:27:03 -315.099176 0.133384
LBFGS: 17 14:27:04 -315.099625 0.092448
LBFGS: 18 14:27:04 -315.100126 0.203717
LBFGS: 19 14:27:05 -315.100897 0.285875
LBFGS: 20 14:27:06 -315.101676 0.246505
Step Time Energy fmax
LBFGS: 0 14:27:06 -314.826849 1.913888
LBFGS: 1 14:27:07 -314.830355 2.630181
LBFGS: 2 14:27:07 -314.879030 1.103464
LBFGS: 3 14:27:08 -314.954075 1.655207
LBFGS: 4 14:27:09 -315.052884 1.750462
LBFGS: 5 14:27:09 -315.070618 0.597039
LBFGS: 6 14:27:10 -315.079431 0.425801
LBFGS: 7 14:27:10 -315.084188 0.774329
LBFGS: 8 14:27:11 -315.093340 1.095935
LBFGS: 9 14:27:11 -315.103773 0.981999
LBFGS: 10 14:27:12 -315.112040 0.316091
LBFGS: 11 14:27:12 -315.113703 0.076469
LBFGS: 12 14:27:13 -315.114383 0.144698
LBFGS: 13 14:27:14 -315.115594 0.214349
LBFGS: 14 14:27:14 -315.116872 0.240932
LBFGS: 15 14:27:14 -315.117906 0.174730
LBFGS: 16 14:27:15 -315.118502 0.082891
LBFGS: 17 14:27:15 -315.118855 0.087769
LBFGS: 18 14:27:16 -315.119350 0.143736
LBFGS: 19 14:27:16 -315.120350 0.215614
LBFGS: 20 14:27:17 -315.121618 0.196765
Step Time Energy fmax
LBFGS: 0 14:27:17 -314.851842 1.981743
LBFGS: 1 14:27:18 -314.854710 2.756767
LBFGS: 2 14:27:19 -314.905255 1.153662
LBFGS: 3 14:27:19 -314.974233 1.622625
LBFGS: 4 14:27:20 -315.057172 2.133789
LBFGS: 5 14:27:20 -315.076445 0.707359
LBFGS: 6 14:27:21 -315.082064 0.317957
LBFGS: 7 14:27:21 -315.084358 0.371272
LBFGS: 8 14:27:22 -315.092300 0.472301
LBFGS: 9 14:27:23 -315.098973 0.418559
LBFGS: 10 14:27:23 -315.102894 0.141617
LBFGS: 11 14:27:24 -315.103800 0.114827
LBFGS: 12 14:27:24 -315.104853 0.217479
LBFGS: 13 14:27:25 -315.106662 0.300952
LBFGS: 14 14:27:25 -315.108456 0.270345
LBFGS: 15 14:27:26 -315.109690 0.151060
LBFGS: 16 14:27:27 -315.110342 0.086839
LBFGS: 17 14:27:27 -315.110994 0.111298
LBFGS: 18 14:27:28 -315.112310 0.195924
LBFGS: 19 14:27:29 -315.114114 0.261454
LBFGS: 20 14:27:29 -315.115619 0.180962
Step Time Energy fmax
LBFGS: 0 14:27:30 -314.781838 1.690655
LBFGS: 1 14:27:30 -314.789059 2.285397
LBFGS: 2 14:27:31 -314.834014 1.065533
LBFGS: 3 14:27:31 -314.955067 1.840421
LBFGS: 4 14:27:32 -314.938150 2.526628
LBFGS: 5 14:27:33 -315.041282 1.219545
LBFGS: 6 14:27:33 -315.069179 0.617948
LBFGS: 7 14:27:34 -315.083783 1.223664
LBFGS: 8 14:27:34 -315.092861 0.794105
LBFGS: 9 14:27:35 -315.111833 0.412962
LBFGS: 10 14:27:36 -315.128464 0.534106
LBFGS: 11 14:27:36 -315.133276 0.539428
LBFGS: 12 14:27:37 -315.137347 0.220372
LBFGS: 13 14:27:37 -315.138419 0.094359
LBFGS: 14 14:27:38 -315.138717 0.093209
LBFGS: 15 14:27:38 -315.139375 0.099889
LBFGS: 16 14:27:39 -315.140227 0.101291
LBFGS: 17 14:27:40 -315.140957 0.075474
LBFGS: 18 14:27:40 -315.141278 0.042126
LBFGS: 19 14:27:41 -315.141451 0.045024
LBFGS: 20 14:27:41 -315.141704 0.066188
Step Time Energy fmax
LBFGS: 0 14:27:42 -314.876033 1.586837
LBFGS: 1 14:27:43 -314.888682 2.276654
LBFGS: 2 14:27:43 -314.937951 1.288270
LBFGS: 3 14:27:44 -315.089267 2.011939
LBFGS: 4 14:27:44 -315.107106 0.569811
LBFGS: 5 14:27:45 -315.110417 0.311919
LBFGS: 6 14:27:46 -315.112088 0.301594
LBFGS: 7 14:27:46 -315.117956 0.248253
LBFGS: 8 14:27:47 -315.123262 0.234842
LBFGS: 9 14:27:47 -315.126475 0.132913
LBFGS: 10 14:27:48 -315.127278 0.120038
LBFGS: 11 14:27:48 -315.128195 0.177597
LBFGS: 12 14:27:49 -315.129901 0.234139
LBFGS: 13 14:27:50 -315.132150 0.229053
LBFGS: 14 14:27:50 -315.134294 0.165622
LBFGS: 15 14:27:51 -315.135561 0.080052
LBFGS: 16 14:27:51 -315.136160 0.066220
LBFGS: 17 14:27:52 -315.136931 0.096559
LBFGS: 18 14:27:52 -315.138140 0.111144
LBFGS: 19 14:27:53 -315.139070 0.068914
LBFGS: 20 14:27:53 -315.139383 0.035744
Step Time Energy fmax
LBFGS: 0 14:27:54 -314.836443 1.764710
LBFGS: 1 14:27:54 -314.845005 2.443023
LBFGS: 2 14:27:55 -314.893456 1.186402
LBFGS: 3 14:27:56 -315.011853 1.977732
LBFGS: 4 14:27:56 -315.063370 1.200329
LBFGS: 5 14:27:57 -315.085959 0.703788
LBFGS: 6 14:27:57 -315.092483 0.313328
LBFGS: 7 14:27:58 -315.098687 0.587824
LBFGS: 8 14:27:58 -315.104088 0.792738
LBFGS: 9 14:27:59 -315.114511 0.893709
LBFGS: 10 14:28:00 -315.120629 0.504779
LBFGS: 11 14:28:00 -315.122776 0.101019
LBFGS: 12 14:28:01 -315.123254 0.147700
LBFGS: 13 14:28:01 -315.124301 0.198209
LBFGS: 14 14:28:02 -315.125518 0.218451
LBFGS: 15 14:28:03 -315.126866 0.190706
LBFGS: 16 14:28:03 -315.127786 0.109131
LBFGS: 17 14:28:04 -315.128342 0.073381
LBFGS: 18 14:28:04 -315.128875 0.119088
LBFGS: 19 14:28:05 -315.129944 0.179643
LBFGS: 20 14:28:06 -315.131299 0.170711
Step Time Energy fmax
LBFGS: 0 14:28:06 -314.834402 2.142807
LBFGS: 1 14:28:07 -314.830620 2.905369
LBFGS: 2 14:28:07 -314.883376 1.040638
LBFGS: 3 14:28:08 -314.929290 1.289909
LBFGS: 4 14:28:08 -315.025674 2.149108
LBFGS: 5 14:28:09 -315.041800 0.932697
LBFGS: 6 14:28:09 -315.061978 0.445068
LBFGS: 7 14:28:10 -315.066558 0.259296
LBFGS: 8 14:28:11 -315.075361 0.831552
LBFGS: 9 14:28:11 -315.081101 0.961846
LBFGS: 10 14:28:12 -315.091298 0.757399
LBFGS: 11 14:28:12 -315.096013 0.240538
LBFGS: 12 14:28:13 -315.097539 0.132738
LBFGS: 13 14:28:13 -315.098761 0.205549
LBFGS: 14 14:28:14 -315.100677 0.247806
LBFGS: 15 14:28:15 -315.102422 0.222405
LBFGS: 16 14:28:15 -315.103496 0.153041
LBFGS: 17 14:28:16 -315.104045 0.051376
LBFGS: 18 14:28:16 -315.104310 0.069424
LBFGS: 19 14:28:17 -315.104669 0.118948
LBFGS: 20 14:28:18 -315.105219 0.134854
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}/")