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 20:12:58 -300.206729 0.046073
LBFGS: 1 20:12:58 -300.207208 0.044109
LBFGS: 2 20:12:59 -300.212885 0.005257
Step Time Energy fmax
LBFGS: 0 20:13:00 -314.863504 1.565261
LBFGS: 1 20:13:00 -314.877969 2.189863
LBFGS: 2 20:13:01 -314.929430 1.335283
LBFGS: 3 20:13:01 -315.089922 1.452583
LBFGS: 4 20:13:02 -315.108185 0.622938
LBFGS: 5 20:13:02 -315.116605 0.280766
LBFGS: 6 20:13:03 -315.119878 0.294298
LBFGS: 7 20:13:03 -315.124880 0.431738
LBFGS: 8 20:13:04 -315.133516 0.613977
LBFGS: 9 20:13:05 -315.138858 0.394161
LBFGS: 10 20:13:05 -315.140805 0.097907
LBFGS: 11 20:13:06 -315.141148 0.131288
LBFGS: 12 20:13:06 -315.142294 0.206384
LBFGS: 13 20:13:07 -315.143886 0.249121
LBFGS: 14 20:13:07 -315.145808 0.227635
LBFGS: 15 20:13:08 -315.147064 0.122328
LBFGS: 16 20:13:09 -315.147576 0.040564
LBFGS: 17 20:13:09 -315.147907 0.051632
LBFGS: 18 20:13:10 -315.148517 0.076985
LBFGS: 19 20:13:10 -315.149134 0.076724
LBFGS: 20 20:13:11 -315.149458 0.030510
Step Time Energy fmax
LBFGS: 0 20:13:11 -314.916205 2.800024
LBFGS: 1 20:13:12 -314.893449 3.561471
LBFGS: 2 20:13:12 -314.969472 1.039453
LBFGS: 3 20:13:13 -314.992902 0.863418
LBFGS: 4 20:13:13 -315.046473 1.800364
LBFGS: 5 20:13:14 -315.103039 1.211531
LBFGS: 6 20:13:15 -315.113030 0.561311
LBFGS: 7 20:13:15 -315.119348 0.343130
LBFGS: 8 20:13:16 -315.122368 0.528654
LBFGS: 9 20:13:16 -315.128865 0.688126
LBFGS: 10 20:13:17 -315.133008 0.484488
LBFGS: 11 20:13:17 -315.135537 0.138821
LBFGS: 12 20:13:18 -315.137147 0.241552
LBFGS: 13 20:13:18 -315.139965 0.452651
LBFGS: 14 20:13:18 -315.144545 0.574007
LBFGS: 15 20:13:19 -315.149118 0.462306
LBFGS: 16 20:13:19 -315.151316 0.190217
LBFGS: 17 20:13:19 -315.152578 0.113092
LBFGS: 18 20:13:20 -315.153673 0.225065
LBFGS: 19 20:13:20 -315.155393 0.355284
LBFGS: 20 20:13:20 -315.157736 0.364418
Step Time Energy fmax
LBFGS: 0 20:13:21 -314.763292 1.805104
LBFGS: 1 20:13:21 -314.764586 2.455956
LBFGS: 2 20:13:22 -314.808440 0.950327
LBFGS: 3 20:13:22 -314.873195 1.495390
LBFGS: 4 20:13:23 -315.025661 1.163683
LBFGS: 5 20:13:24 -315.043050 0.637277
LBFGS: 6 20:13:24 -315.070332 1.232066
LBFGS: 7 20:13:25 -315.080401 1.408229
LBFGS: 8 20:13:25 -315.104677 1.076107
LBFGS: 9 20:13:26 -315.116579 1.403434
LBFGS: 10 20:13:26 -315.128964 0.138812
LBFGS: 11 20:13:27 -315.130437 0.085057
LBFGS: 12 20:13:27 -315.131307 0.076887
LBFGS: 13 20:13:28 -315.132045 0.062998
LBFGS: 14 20:13:28 -315.133448 0.093806
LBFGS: 15 20:13:29 -315.134216 0.087883
LBFGS: 16 20:13:29 -315.134572 0.049129
LBFGS: 17 20:13:30 -315.134726 0.039547
LBFGS: 18 20:13:30 -315.134971 0.051624
LBFGS: 19 20:13:31 -315.135360 0.068355
LBFGS: 20 20:13:32 -315.135771 0.053757
Step Time Energy fmax
LBFGS: 0 20:13:32 -314.866866 2.220352
LBFGS: 1 20:13:33 -314.862471 3.042695
LBFGS: 2 20:13:33 -314.917841 1.107917
LBFGS: 3 20:13:34 -314.962204 1.253191
LBFGS: 4 20:13:34 -315.038730 2.296851
LBFGS: 5 20:13:35 -315.063995 0.984875
LBFGS: 6 20:13:36 -315.073617 0.282307
LBFGS: 7 20:13:36 -315.075443 0.218177
LBFGS: 8 20:13:37 -315.079142 0.536424
LBFGS: 9 20:13:37 -315.084150 0.702014
LBFGS: 10 20:13:38 -315.088371 0.537678
LBFGS: 11 20:13:38 -315.090654 0.184732
LBFGS: 12 20:13:39 -315.091847 0.190443
LBFGS: 13 20:13:40 -315.093462 0.396839
LBFGS: 14 20:13:40 -315.096026 0.516514
LBFGS: 15 20:13:41 -315.098216 0.377530
LBFGS: 16 20:13:41 -315.099174 0.133355
LBFGS: 17 20:13:42 -315.099623 0.092466
LBFGS: 18 20:13:42 -315.100123 0.203527
LBFGS: 19 20:13:43 -315.100896 0.286185
LBFGS: 20 20:13:43 -315.101678 0.246652
Step Time Energy fmax
LBFGS: 0 20:13:44 -314.826850 1.913887
LBFGS: 1 20:13:45 -314.830356 2.630181
LBFGS: 2 20:13:45 -314.879031 1.103464
LBFGS: 3 20:13:46 -314.954077 1.655207
LBFGS: 4 20:13:46 -315.052882 1.750462
LBFGS: 5 20:13:47 -315.070617 0.597039
LBFGS: 6 20:13:47 -315.079432 0.425802
LBFGS: 7 20:13:48 -315.084189 0.774328
LBFGS: 8 20:13:48 -315.093336 1.095935
LBFGS: 9 20:13:49 -315.103773 0.982011
LBFGS: 10 20:13:49 -315.112038 0.316091
LBFGS: 11 20:13:50 -315.113703 0.076469
LBFGS: 12 20:13:51 -315.114383 0.144709
LBFGS: 13 20:13:51 -315.115592 0.214337
LBFGS: 14 20:13:52 -315.116876 0.240921
LBFGS: 15 20:13:52 -315.117911 0.174739
LBFGS: 16 20:13:53 -315.118503 0.082891
LBFGS: 17 20:13:53 -315.118852 0.087761
LBFGS: 18 20:13:54 -315.119351 0.143736
LBFGS: 19 20:13:54 -315.120350 0.215748
LBFGS: 20 20:13:55 -315.121620 0.196565
Step Time Energy fmax
LBFGS: 0 20:13:56 -314.851843 1.981744
LBFGS: 1 20:13:56 -314.854711 2.756767
LBFGS: 2 20:13:57 -314.905253 1.153661
LBFGS: 3 20:13:57 -314.974236 1.622625
LBFGS: 4 20:13:58 -315.057173 2.133789
LBFGS: 5 20:13:58 -315.076448 0.707359
LBFGS: 6 20:13:59 -315.082066 0.317957
LBFGS: 7 20:13:59 -315.084356 0.371427
LBFGS: 8 20:14:00 -315.092305 0.471882
LBFGS: 9 20:14:00 -315.098973 0.418702
LBFGS: 10 20:14:01 -315.102895 0.141647
LBFGS: 11 20:14:02 -315.103798 0.114783
LBFGS: 12 20:14:02 -315.104857 0.217490
LBFGS: 13 20:14:03 -315.106656 0.300890
LBFGS: 14 20:14:03 -315.108456 0.270570
LBFGS: 15 20:14:04 -315.109695 0.151017
LBFGS: 16 20:14:04 -315.110345 0.086795
LBFGS: 17 20:14:05 -315.110997 0.111398
LBFGS: 18 20:14:05 -315.112308 0.195660
LBFGS: 19 20:14:06 -315.114120 0.261428
LBFGS: 20 20:14:06 -315.115618 0.181364
Step Time Energy fmax
LBFGS: 0 20:14:07 -314.781832 1.690654
LBFGS: 1 20:14:07 -314.789063 2.285398
LBFGS: 2 20:14:08 -314.834016 1.065533
LBFGS: 3 20:14:08 -314.955072 1.840420
LBFGS: 4 20:14:09 -314.938156 2.526572
LBFGS: 5 20:14:09 -315.041288 1.219543
LBFGS: 6 20:14:10 -315.069181 0.617947
LBFGS: 7 20:14:11 -315.083787 1.223674
LBFGS: 8 20:14:11 -315.092860 0.794106
LBFGS: 9 20:14:12 -315.111830 0.412962
LBFGS: 10 20:14:12 -315.128465 0.534108
LBFGS: 11 20:14:13 -315.133278 0.539399
LBFGS: 12 20:14:13 -315.137347 0.220405
LBFGS: 13 20:14:13 -315.138420 0.094373
LBFGS: 14 20:14:14 -315.138718 0.093197
LBFGS: 15 20:14:14 -315.139372 0.099809
LBFGS: 16 20:14:15 -315.140226 0.101416
LBFGS: 17 20:14:15 -315.140958 0.075472
LBFGS: 18 20:14:15 -315.141279 0.042109
LBFGS: 19 20:14:16 -315.141450 0.044841
LBFGS: 20 20:14:16 -315.141707 0.066579
Step Time Energy fmax
LBFGS: 0 20:14:17 -314.876032 1.586837
LBFGS: 1 20:14:17 -314.888684 2.276653
LBFGS: 2 20:14:17 -314.937947 1.288269
LBFGS: 3 20:14:18 -315.089267 2.011935
LBFGS: 4 20:14:18 -315.107109 0.569798
LBFGS: 5 20:14:18 -315.110415 0.311920
LBFGS: 6 20:14:19 -315.112090 0.301595
LBFGS: 7 20:14:19 -315.117956 0.248256
LBFGS: 8 20:14:20 -315.123261 0.234828
LBFGS: 9 20:14:20 -315.126473 0.132931
LBFGS: 10 20:14:20 -315.127281 0.120038
LBFGS: 11 20:14:21 -315.128195 0.177557
LBFGS: 12 20:14:21 -315.129903 0.234316
LBFGS: 13 20:14:22 -315.132152 0.228796
LBFGS: 14 20:14:22 -315.134295 0.165720
LBFGS: 15 20:14:22 -315.135563 0.080075
LBFGS: 16 20:14:23 -315.136163 0.066211
LBFGS: 17 20:14:23 -315.136935 0.096581
LBFGS: 18 20:14:24 -315.138138 0.111135
LBFGS: 19 20:14:24 -315.139071 0.068902
LBFGS: 20 20:14:24 -315.139384 0.035692
Step Time Energy fmax
LBFGS: 0 20:14:25 -314.836445 1.764710
LBFGS: 1 20:14:25 -314.845003 2.443024
LBFGS: 2 20:14:25 -314.893460 1.186403
LBFGS: 3 20:14:26 -315.011852 1.977732
LBFGS: 4 20:14:26 -315.063375 1.200141
LBFGS: 5 20:14:27 -315.085957 0.703955
LBFGS: 6 20:14:27 -315.092485 0.313335
LBFGS: 7 20:14:27 -315.098685 0.587634
LBFGS: 8 20:14:28 -315.104090 0.792747
LBFGS: 9 20:14:28 -315.114505 0.893930
LBFGS: 10 20:14:28 -315.120624 0.505203
LBFGS: 11 20:14:29 -315.122776 0.101109
LBFGS: 12 20:14:29 -315.123256 0.147591
LBFGS: 13 20:14:30 -315.124300 0.198160
LBFGS: 14 20:14:30 -315.125518 0.218173
LBFGS: 15 20:14:30 -315.126866 0.190231
LBFGS: 16 20:14:31 -315.127790 0.109176
LBFGS: 17 20:14:31 -315.128341 0.073348
LBFGS: 18 20:14:32 -315.128878 0.118901
LBFGS: 19 20:14:32 -315.129943 0.179792
LBFGS: 20 20:14:32 -315.131299 0.170364
Step Time Energy fmax
LBFGS: 0 20:14:33 -314.834405 2.142809
LBFGS: 1 20:14:33 -314.830621 2.905369
LBFGS: 2 20:14:34 -314.883377 1.040638
LBFGS: 3 20:14:34 -314.929292 1.289909
LBFGS: 4 20:14:34 -315.025675 2.149109
LBFGS: 5 20:14:35 -315.041801 0.932674
LBFGS: 6 20:14:35 -315.061976 0.445062
LBFGS: 7 20:14:36 -315.066557 0.259294
LBFGS: 8 20:14:36 -315.075359 0.831731
LBFGS: 9 20:14:36 -315.081106 0.961644
LBFGS: 10 20:14:37 -315.091300 0.757281
LBFGS: 11 20:14:37 -315.096013 0.240514
LBFGS: 12 20:14:38 -315.097543 0.133016
LBFGS: 13 20:14:38 -315.098763 0.205325
LBFGS: 14 20:14:39 -315.100679 0.247697
LBFGS: 15 20:14:39 -315.102424 0.222190
LBFGS: 16 20:14:40 -315.103502 0.153028
LBFGS: 17 20:14:40 -315.104044 0.051243
LBFGS: 18 20:14:41 -315.104311 0.069414
LBFGS: 19 20:14:41 -315.104670 0.118971
LBFGS: 20 20:14:41 -315.105218 0.134707
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}/")