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 22:04:35 -300.206729 0.046073
LBFGS: 1 22:04:36 -300.207208 0.044109
LBFGS: 2 22:04:36 -300.212885 0.005257
Step Time Energy fmax
LBFGS: 0 22:04:37 -314.863499 1.565261
LBFGS: 1 22:04:37 -314.877964 2.190013
LBFGS: 2 22:04:38 -314.929429 1.335110
LBFGS: 3 22:04:38 -315.089963 1.452216
LBFGS: 4 22:04:38 -315.108200 0.622644
LBFGS: 5 22:04:39 -315.116611 0.280646
LBFGS: 6 22:04:39 -315.119881 0.294402
LBFGS: 7 22:04:40 -315.124891 0.431985
LBFGS: 8 22:04:40 -315.133513 0.614492
LBFGS: 9 22:04:41 -315.138862 0.393736
LBFGS: 10 22:04:41 -315.140804 0.097682
LBFGS: 11 22:04:41 -315.141148 0.131267
LBFGS: 12 22:04:42 -315.142293 0.206898
LBFGS: 13 22:04:42 -315.143880 0.250079
LBFGS: 14 22:04:43 -315.145809 0.228490
LBFGS: 15 22:04:43 -315.147065 0.122603
LBFGS: 16 22:04:43 -315.147575 0.040568
LBFGS: 17 22:04:44 -315.147907 0.051684
LBFGS: 18 22:04:44 -315.148517 0.077293
LBFGS: 19 22:04:45 -315.149132 0.077188
LBFGS: 20 22:04:45 -315.149459 0.030560
Step Time Energy fmax
LBFGS: 0 22:04:46 -314.916204 2.800023
LBFGS: 1 22:04:46 -314.893446 3.561471
LBFGS: 2 22:04:47 -314.969472 1.039454
LBFGS: 3 22:04:47 -314.992898 0.863418
LBFGS: 4 22:04:48 -315.046472 1.800363
LBFGS: 5 22:04:48 -315.103040 1.211531
LBFGS: 6 22:04:49 -315.113029 0.561478
LBFGS: 7 22:04:49 -315.119350 0.343509
LBFGS: 8 22:04:50 -315.122369 0.528589
LBFGS: 9 22:04:51 -315.128870 0.687940
LBFGS: 10 22:04:51 -315.133013 0.483684
LBFGS: 11 22:04:52 -315.135536 0.138833
LBFGS: 12 22:04:52 -315.137150 0.241889
LBFGS: 13 22:04:53 -315.139969 0.452876
LBFGS: 14 22:04:53 -315.144548 0.573945
LBFGS: 15 22:04:54 -315.149122 0.461643
LBFGS: 16 22:04:54 -315.151319 0.190019
LBFGS: 17 22:04:55 -315.152578 0.113423
LBFGS: 18 22:04:55 -315.153671 0.224860
LBFGS: 19 22:04:56 -315.155398 0.355633
LBFGS: 20 22:04:56 -315.157737 0.364023
Step Time Energy fmax
LBFGS: 0 22:04:57 -314.763296 1.805104
LBFGS: 1 22:04:57 -314.764588 2.455956
LBFGS: 2 22:04:58 -314.808440 0.950326
LBFGS: 3 22:04:58 -314.873193 1.495389
LBFGS: 4 22:04:59 -315.025657 1.163682
LBFGS: 5 22:04:59 -315.043046 0.637277
LBFGS: 6 22:05:00 -315.070334 1.232049
LBFGS: 7 22:05:00 -315.080401 1.408271
LBFGS: 8 22:05:01 -315.104672 1.076272
LBFGS: 9 22:05:01 -315.116586 1.402648
LBFGS: 10 22:05:02 -315.128965 0.138956
LBFGS: 11 22:05:02 -315.130439 0.085053
LBFGS: 12 22:05:03 -315.131306 0.076895
LBFGS: 13 22:05:03 -315.132045 0.063007
LBFGS: 14 22:05:04 -315.133452 0.093732
LBFGS: 15 22:05:04 -315.134214 0.087900
LBFGS: 16 22:05:05 -315.134570 0.049230
LBFGS: 17 22:05:05 -315.134731 0.039574
LBFGS: 18 22:05:06 -315.134966 0.051646
LBFGS: 19 22:05:06 -315.135359 0.068573
LBFGS: 20 22:05:07 -315.135770 0.053784
Step Time Energy fmax
LBFGS: 0 22:05:07 -314.866862 2.220352
LBFGS: 1 22:05:08 -314.862474 3.042696
LBFGS: 2 22:05:08 -314.917843 1.107918
LBFGS: 3 22:05:08 -314.962207 1.253192
LBFGS: 4 22:05:09 -315.038730 2.296851
LBFGS: 5 22:05:09 -315.063997 0.984886
LBFGS: 6 22:05:10 -315.073618 0.282307
LBFGS: 7 22:05:10 -315.075442 0.218173
LBFGS: 8 22:05:11 -315.079142 0.536246
LBFGS: 9 22:05:11 -315.084153 0.702058
LBFGS: 10 22:05:12 -315.088371 0.537791
LBFGS: 11 22:05:12 -315.090654 0.184745
LBFGS: 12 22:05:13 -315.091846 0.190632
LBFGS: 13 22:05:13 -315.093460 0.396350
LBFGS: 14 22:05:14 -315.096029 0.516738
LBFGS: 15 22:05:14 -315.098212 0.377609
LBFGS: 16 22:05:15 -315.099180 0.133247
LBFGS: 17 22:05:15 -315.099627 0.092456
LBFGS: 18 22:05:16 -315.100124 0.203669
LBFGS: 19 22:05:16 -315.100896 0.286080
LBFGS: 20 22:05:17 -315.101679 0.246392
Step Time Energy fmax
LBFGS: 0 22:05:17 -314.826850 1.913888
LBFGS: 1 22:05:18 -314.830357 2.630181
LBFGS: 2 22:05:18 -314.879032 1.103464
LBFGS: 3 22:05:19 -314.954076 1.655207
LBFGS: 4 22:05:19 -315.052882 1.750462
LBFGS: 5 22:05:20 -315.070618 0.597039
LBFGS: 6 22:05:20 -315.079429 0.425801
LBFGS: 7 22:05:21 -315.084187 0.774328
LBFGS: 8 22:05:21 -315.093336 1.095935
LBFGS: 9 22:05:22 -315.103774 0.981999
LBFGS: 10 22:05:22 -315.112038 0.316090
LBFGS: 11 22:05:23 -315.113704 0.076469
LBFGS: 12 22:05:23 -315.114382 0.144709
LBFGS: 13 22:05:24 -315.115595 0.214326
LBFGS: 14 22:05:25 -315.116872 0.240933
LBFGS: 15 22:05:25 -315.117906 0.174889
LBFGS: 16 22:05:26 -315.118503 0.082566
LBFGS: 17 22:05:26 -315.118853 0.087449
LBFGS: 18 22:05:27 -315.119355 0.143927
LBFGS: 19 22:05:27 -315.120350 0.215684
LBFGS: 20 22:05:28 -315.121616 0.196798
Step Time Energy fmax
LBFGS: 0 22:05:28 -314.851842 1.981744
LBFGS: 1 22:05:29 -314.854715 2.756767
LBFGS: 2 22:05:29 -314.905254 1.153662
LBFGS: 3 22:05:30 -314.974232 1.622624
LBFGS: 4 22:05:30 -315.057173 2.133789
LBFGS: 5 22:05:30 -315.076448 0.707359
LBFGS: 6 22:05:31 -315.082063 0.317957
LBFGS: 7 22:05:31 -315.084358 0.371273
LBFGS: 8 22:05:32 -315.092301 0.472301
LBFGS: 9 22:05:32 -315.098972 0.418561
LBFGS: 10 22:05:33 -315.102900 0.141619
LBFGS: 11 22:05:33 -315.103799 0.114823
LBFGS: 12 22:05:34 -315.104854 0.217416
LBFGS: 13 22:05:34 -315.106658 0.301178
LBFGS: 14 22:05:35 -315.108454 0.270246
LBFGS: 15 22:05:35 -315.109691 0.151095
LBFGS: 16 22:05:36 -315.110342 0.086800
LBFGS: 17 22:05:36 -315.110999 0.111556
LBFGS: 18 22:05:37 -315.112306 0.195577
LBFGS: 19 22:05:37 -315.114119 0.261372
LBFGS: 20 22:05:37 -315.115620 0.181531
Step Time Energy fmax
LBFGS: 0 22:05:38 -314.781834 1.690654
LBFGS: 1 22:05:38 -314.789063 2.285398
LBFGS: 2 22:05:39 -314.834020 1.065533
LBFGS: 3 22:05:39 -314.955069 1.840420
LBFGS: 4 22:05:40 -314.938155 2.526573
LBFGS: 5 22:05:40 -315.041284 1.219543
LBFGS: 6 22:05:41 -315.069178 0.617946
LBFGS: 7 22:05:42 -315.083784 1.223674
LBFGS: 8 22:05:42 -315.092863 0.794107
LBFGS: 9 22:05:43 -315.111830 0.412969
LBFGS: 10 22:05:43 -315.128463 0.534123
LBFGS: 11 22:05:44 -315.133277 0.539401
LBFGS: 12 22:05:44 -315.137347 0.220428
LBFGS: 13 22:05:45 -315.138418 0.094550
LBFGS: 14 22:05:45 -315.138719 0.093173
LBFGS: 15 22:05:46 -315.139373 0.099639
LBFGS: 16 22:05:46 -315.140227 0.100917
LBFGS: 17 22:05:47 -315.140955 0.075595
LBFGS: 18 22:05:47 -315.141281 0.042106
LBFGS: 19 22:05:48 -315.141452 0.044869
LBFGS: 20 22:05:48 -315.141705 0.066083
Step Time Energy fmax
LBFGS: 0 22:05:49 -314.876032 1.586837
LBFGS: 1 22:05:49 -314.888684 2.276651
LBFGS: 2 22:05:50 -314.937947 1.288269
LBFGS: 3 22:05:50 -315.089268 2.011935
LBFGS: 4 22:05:51 -315.107106 0.569822
LBFGS: 5 22:05:51 -315.110421 0.311919
LBFGS: 6 22:05:52 -315.112087 0.301595
LBFGS: 7 22:05:52 -315.117954 0.248278
LBFGS: 8 22:05:53 -315.123262 0.234829
LBFGS: 9 22:05:53 -315.126474 0.132929
LBFGS: 10 22:05:54 -315.127277 0.120049
LBFGS: 11 22:05:54 -315.128194 0.177875
LBFGS: 12 22:05:55 -315.129903 0.233528
LBFGS: 13 22:05:55 -315.132152 0.229288
LBFGS: 14 22:05:56 -315.134297 0.165474
LBFGS: 15 22:05:56 -315.135560 0.080031
LBFGS: 16 22:05:57 -315.136163 0.066219
LBFGS: 17 22:05:57 -315.136936 0.096564
LBFGS: 18 22:05:58 -315.138138 0.111142
LBFGS: 19 22:05:58 -315.139071 0.068907
LBFGS: 20 22:05:59 -315.139383 0.035865
Step Time Energy fmax
LBFGS: 0 22:05:59 -314.836442 1.764710
LBFGS: 1 22:06:00 -314.845007 2.443023
LBFGS: 2 22:06:00 -314.893455 1.186401
LBFGS: 3 22:06:01 -315.011856 1.977733
LBFGS: 4 22:06:01 -315.063371 1.200140
LBFGS: 5 22:06:02 -315.085955 0.703964
LBFGS: 6 22:06:02 -315.092481 0.313335
LBFGS: 7 22:06:03 -315.098689 0.587634
LBFGS: 8 22:06:03 -315.104091 0.792747
LBFGS: 9 22:06:04 -315.114507 0.893940
LBFGS: 10 22:06:04 -315.120627 0.505030
LBFGS: 11 22:06:05 -315.122776 0.100745
LBFGS: 12 22:06:05 -315.123256 0.147570
LBFGS: 13 22:06:06 -315.124297 0.198962
LBFGS: 14 22:06:06 -315.125516 0.218182
LBFGS: 15 22:06:07 -315.126866 0.191031
LBFGS: 16 22:06:08 -315.127785 0.109359
LBFGS: 17 22:06:08 -315.128341 0.073449
LBFGS: 18 22:06:09 -315.128873 0.118939
LBFGS: 19 22:06:09 -315.129941 0.180019
LBFGS: 20 22:06:10 -315.131297 0.170663
Step Time Energy fmax
LBFGS: 0 22:06:10 -314.834401 2.142809
LBFGS: 1 22:06:10 -314.830621 2.905369
LBFGS: 2 22:06:11 -314.883377 1.040639
LBFGS: 3 22:06:12 -314.929292 1.289909
LBFGS: 4 22:06:12 -315.025671 2.149108
LBFGS: 5 22:06:13 -315.041802 0.932675
LBFGS: 6 22:06:13 -315.061976 0.445063
LBFGS: 7 22:06:14 -315.066560 0.259294
LBFGS: 8 22:06:14 -315.075361 0.831731
LBFGS: 9 22:06:15 -315.081100 0.961644
LBFGS: 10 22:06:15 -315.091299 0.757289
LBFGS: 11 22:06:16 -315.096017 0.240363
LBFGS: 12 22:06:16 -315.097540 0.132868
LBFGS: 13 22:06:17 -315.098764 0.205347
LBFGS: 14 22:06:17 -315.100679 0.247612
LBFGS: 15 22:06:18 -315.102423 0.222646
LBFGS: 16 22:06:18 -315.103497 0.152610
LBFGS: 17 22:06:19 -315.104048 0.051565
LBFGS: 18 22:06:19 -315.104306 0.069503
LBFGS: 19 22:06:20 -315.104674 0.119160
LBFGS: 20 22:06:20 -315.105221 0.134746
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}/")