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...
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 00:26:29 -300.206729 0.046073
LBFGS: 1 00:26:29 -300.207208 0.044108
LBFGS: 2 00:26:30 -300.212886 0.005266
Step Time Energy fmax
LBFGS: 0 00:26:30 -314.854281 1.556090
LBFGS: 1 00:26:31 -314.868858 2.154186
LBFGS: 2 00:26:32 -314.920341 1.326128
LBFGS: 3 00:26:32 -315.083095 1.175546
LBFGS: 4 00:26:32 -315.102426 0.692285
LBFGS: 5 00:26:33 -315.114038 0.336518
LBFGS: 6 00:26:34 -315.118452 0.347919
LBFGS: 7 00:26:34 -315.123725 0.469725
LBFGS: 8 00:26:35 -315.135303 0.739684
LBFGS: 9 00:26:35 -315.141057 0.442964
LBFGS: 10 00:26:36 -315.143258 0.107758
LBFGS: 11 00:26:36 -315.143595 0.114599
LBFGS: 12 00:26:37 -315.144383 0.151237
LBFGS: 13 00:26:37 -315.145764 0.184481
LBFGS: 14 00:26:38 -315.147507 0.192245
LBFGS: 15 00:26:38 -315.148854 0.131996
LBFGS: 16 00:26:39 -315.149504 0.037469
LBFGS: 17 00:26:39 -315.149765 0.036069
LBFGS: 18 00:26:40 -315.150106 0.059375
LBFGS: 19 00:26:41 -315.150626 0.069156
LBFGS: 20 00:26:41 -315.151066 0.040419
Step Time Energy fmax
LBFGS: 0 00:26:42 -314.795045 1.856075
LBFGS: 1 00:26:42 -314.797509 2.532072
LBFGS: 2 00:26:43 -314.843217 1.027854
LBFGS: 3 00:26:43 -314.913809 1.585636
LBFGS: 4 00:26:44 -315.037367 1.523217
LBFGS: 5 00:26:45 -315.055762 0.607393
LBFGS: 6 00:26:45 -315.072534 0.976536
LBFGS: 7 00:26:46 -315.080981 1.047900
LBFGS: 8 00:26:46 -315.094352 1.440238
LBFGS: 9 00:26:47 -315.112547 1.021013
LBFGS: 10 00:26:47 -315.124566 0.261576
LBFGS: 11 00:26:48 -315.127311 0.204783
LBFGS: 12 00:26:48 -315.127996 0.200211
LBFGS: 13 00:26:49 -315.128526 0.145421
LBFGS: 14 00:26:49 -315.129980 0.066395
LBFGS: 15 00:26:50 -315.130755 0.069179
LBFGS: 16 00:26:50 -315.131162 0.054456
LBFGS: 17 00:26:51 -315.131317 0.046510
LBFGS: 18 00:26:51 -315.131661 0.043753
LBFGS: 19 00:26:52 -315.132132 0.058862
LBFGS: 20 00:26:53 -315.132654 0.062859
Step Time Energy fmax
LBFGS: 0 00:26:53 -314.823333 2.159221
LBFGS: 1 00:26:54 -314.818334 2.916067
LBFGS: 2 00:26:54 -314.871532 1.014593
LBFGS: 3 00:26:55 -314.914631 1.245859
LBFGS: 4 00:26:55 -315.014809 2.114391
LBFGS: 5 00:26:56 -315.022249 1.194785
LBFGS: 6 00:26:56 -315.053261 0.564590
LBFGS: 7 00:26:57 -315.058970 0.286271
LBFGS: 8 00:26:57 -315.068869 0.843531
LBFGS: 9 00:26:58 -315.074464 0.941920
LBFGS: 10 00:26:58 -315.088915 0.744430
LBFGS: 11 00:26:59 -315.093511 0.276410
LBFGS: 12 00:27:00 -315.095784 0.112959
LBFGS: 13 00:27:00 -315.097095 0.174329
LBFGS: 14 00:27:01 -315.098818 0.209857
LBFGS: 15 00:27:01 -315.100602 0.221255
LBFGS: 16 00:27:02 -315.101801 0.153644
LBFGS: 17 00:27:02 -315.102401 0.060305
LBFGS: 18 00:27:03 -315.102643 0.056581
LBFGS: 19 00:27:03 -315.102900 0.091646
LBFGS: 20 00:27:04 -315.103365 0.121179
Step Time Energy fmax
LBFGS: 0 00:27:04 -314.856635 2.197804
LBFGS: 1 00:27:05 -314.852501 2.998370
LBFGS: 2 00:27:05 -314.907136 1.086294
LBFGS: 3 00:27:06 -314.952236 1.270157
LBFGS: 4 00:27:07 -315.034762 2.249470
LBFGS: 5 00:27:07 -315.058642 0.893996
LBFGS: 6 00:27:08 -315.070128 0.337406
LBFGS: 7 00:27:08 -315.072815 0.247249
LBFGS: 8 00:27:09 -315.077459 0.612706
LBFGS: 9 00:27:09 -315.083180 0.816726
LBFGS: 10 00:27:10 -315.088539 0.668781
LBFGS: 11 00:27:10 -315.092045 0.222090
LBFGS: 12 00:27:10 -315.093186 0.156404
LBFGS: 13 00:27:11 -315.094454 0.302984
LBFGS: 14 00:27:11 -315.096744 0.395763
LBFGS: 15 00:27:12 -315.098494 0.295116
LBFGS: 16 00:27:12 -315.099316 0.137127
LBFGS: 17 00:27:12 -315.099707 0.067318
LBFGS: 18 00:27:13 -315.100049 0.136354
LBFGS: 19 00:27:13 -315.100644 0.207229
LBFGS: 20 00:27:14 -315.101280 0.188624
Step Time Energy fmax
LBFGS: 0 00:27:14 -314.855340 2.229030
LBFGS: 1 00:27:14 -314.850540 3.030822
LBFGS: 2 00:27:15 -314.906147 1.087605
LBFGS: 3 00:27:15 -314.950382 1.256731
LBFGS: 4 00:27:16 -315.033648 2.260729
LBFGS: 5 00:27:16 -315.057824 0.917103
LBFGS: 6 00:27:16 -315.070121 0.365095
LBFGS: 7 00:27:17 -315.072926 0.229026
LBFGS: 8 00:27:17 -315.077457 0.594005
LBFGS: 9 00:27:17 -315.083025 0.799231
LBFGS: 10 00:27:18 -315.088266 0.658384
LBFGS: 11 00:27:18 -315.091598 0.224886
LBFGS: 12 00:27:19 -315.092630 0.154620
LBFGS: 13 00:27:19 -315.093737 0.301368
LBFGS: 14 00:27:19 -315.095835 0.413441
LBFGS: 15 00:27:20 -315.097561 0.329775
LBFGS: 16 00:27:20 -315.098452 0.155956
LBFGS: 17 00:27:21 -315.098904 0.078059
LBFGS: 18 00:27:21 -315.099378 0.173277
LBFGS: 19 00:27:21 -315.100167 0.265101
LBFGS: 20 00:27:22 -315.101069 0.252737
Step Time Energy fmax
LBFGS: 0 00:27:22 -314.812932 2.422293
LBFGS: 1 00:27:23 -314.797210 3.183495
LBFGS: 2 00:27:23 -314.857501 0.945520
LBFGS: 3 00:27:23 -314.883071 0.990615
LBFGS: 4 00:27:24 -314.967109 1.962568
LBFGS: 5 00:27:24 -314.848493 3.634282
LBFGS: 6 00:27:25 -315.018380 1.196381
LBFGS: 7 00:27:25 -315.039450 0.620008
LBFGS: 8 00:27:25 -315.052065 1.037042
LBFGS: 9 00:27:26 -315.059620 0.474454
LBFGS: 10 00:27:26 -315.067397 0.365053
LBFGS: 11 00:27:27 -315.085048 0.331096
LBFGS: 12 00:27:27 -315.088896 0.425077
LBFGS: 13 00:27:27 -315.092113 0.345183
LBFGS: 14 00:27:28 -315.095463 0.114437
LBFGS: 15 00:27:28 -315.096790 0.190389
LBFGS: 16 00:27:29 -315.098643 0.308200
LBFGS: 17 00:27:29 -315.101166 0.335434
LBFGS: 18 00:27:29 -315.103047 0.221501
LBFGS: 19 00:27:30 -315.104157 0.108059
LBFGS: 20 00:27:30 -315.104864 0.102758
Step Time Energy fmax
LBFGS: 0 00:27:30 -314.782610 1.690422
LBFGS: 1 00:27:30 -314.789808 2.287014
LBFGS: 2 00:27:31 -314.834741 1.066046
LBFGS: 3 00:27:31 -314.955309 1.840019
LBFGS: 4 00:27:31 -314.942474 2.482912
LBFGS: 5 00:27:31 -315.041932 1.212970
LBFGS: 6 00:27:32 -315.069475 0.612659
LBFGS: 7 00:27:32 -315.083980 1.204589
LBFGS: 8 00:27:32 -315.092938 0.798604
LBFGS: 9 00:27:33 -315.112851 0.409521
LBFGS: 10 00:27:33 -315.128461 0.557066
LBFGS: 11 00:27:33 -315.133172 0.529025
LBFGS: 12 00:27:34 -315.137242 0.183090
LBFGS: 13 00:27:34 -315.138166 0.091520
LBFGS: 14 00:27:35 -315.138466 0.095074
LBFGS: 15 00:27:35 -315.139132 0.104063
LBFGS: 16 00:27:36 -315.139986 0.105861
LBFGS: 17 00:27:36 -315.140718 0.078126
LBFGS: 18 00:27:37 -315.141038 0.041540
LBFGS: 19 00:27:37 -315.141213 0.046169
LBFGS: 20 00:27:38 -315.141471 0.070003
Step Time Energy fmax
LBFGS: 0 00:27:38 -314.750883 1.789548
LBFGS: 1 00:27:39 -314.751728 2.432863
LBFGS: 2 00:27:39 -314.794930 0.924950
LBFGS: 3 00:27:39 -314.857467 1.467674
LBFGS: 4 00:27:40 -315.021731 1.024036
LBFGS: 5 00:27:41 -315.039276 0.672659
LBFGS: 6 00:27:41 -315.071759 1.523218
LBFGS: 7 00:27:41 -315.081591 1.175005
LBFGS: 8 00:27:42 -315.103268 1.630470
LBFGS: 9 00:27:42 -315.123300 0.471299
LBFGS: 10 00:27:43 -315.131797 0.229836
LBFGS: 11 00:27:43 -315.133072 0.074546
LBFGS: 12 00:27:44 -315.133635 0.068932
LBFGS: 13 00:27:44 -315.134462 0.130982
LBFGS: 14 00:27:45 -315.135439 0.123292
LBFGS: 15 00:27:45 -315.136173 0.099676
LBFGS: 16 00:27:46 -315.136462 0.042927
LBFGS: 17 00:27:46 -315.136615 0.041206
LBFGS: 18 00:27:47 -315.136858 0.065151
LBFGS: 19 00:27:47 -315.137249 0.083934
LBFGS: 20 00:27:48 -315.137631 0.058962
Step Time Energy fmax
LBFGS: 0 00:27:48 -314.789222 2.054604
LBFGS: 1 00:27:49 -314.783592 2.789832
LBFGS: 2 00:27:49 -314.832320 0.938511
LBFGS: 3 00:27:49 -314.871033 1.193900
LBFGS: 4 00:27:50 -314.986550 1.989097
LBFGS: 5 00:27:50 -314.875224 3.273386
LBFGS: 6 00:27:51 -315.024399 0.850128
LBFGS: 7 00:27:51 -315.037328 0.423753
LBFGS: 8 00:27:52 -315.052229 1.363865
LBFGS: 9 00:27:52 -315.060591 1.003264
LBFGS: 10 00:27:53 -315.087098 0.479238
LBFGS: 11 00:27:53 -315.097309 0.597938
LBFGS: 12 00:27:53 -315.103314 0.409684
LBFGS: 13 00:27:54 -315.109197 0.147936
LBFGS: 14 00:27:54 -315.111226 0.140436
LBFGS: 15 00:27:55 -315.112350 0.237334
LBFGS: 16 00:27:55 -315.113988 0.170675
LBFGS: 17 00:27:56 -315.115851 0.251785
LBFGS: 18 00:27:56 -315.116931 0.095491
LBFGS: 19 00:27:57 -315.117296 0.048227
LBFGS: 20 00:27:57 -315.117512 0.069155
Step Time Energy fmax
LBFGS: 0 00:27:58 -314.931710 2.799721
LBFGS: 1 00:27:58 -314.909430 3.574820
LBFGS: 2 00:27:58 -314.986486 1.046463
LBFGS: 3 00:27:59 -315.011027 0.854832
LBFGS: 4 00:27:59 -315.062253 1.739463
LBFGS: 5 00:28:00 -315.105539 1.138611
LBFGS: 6 00:28:00 -315.113828 0.476143
LBFGS: 7 00:28:01 -315.118098 0.280629
LBFGS: 8 00:28:01 -315.120656 0.488842
LBFGS: 9 00:28:02 -315.126363 0.732637
LBFGS: 10 00:28:02 -315.130812 0.639046
LBFGS: 11 00:28:03 -315.134411 0.268220
LBFGS: 12 00:28:03 -315.135990 0.148211
LBFGS: 13 00:28:04 -315.137685 0.257806
LBFGS: 14 00:28:04 -315.140915 0.358744
LBFGS: 15 00:28:05 -315.143625 0.252029
LBFGS: 16 00:28:05 -315.144608 0.163749
LBFGS: 17 00:28:05 -315.145185 0.047384
LBFGS: 18 00:28:06 -315.145507 0.086373
LBFGS: 19 00:28:06 -315.145797 0.141219
LBFGS: 20 00:28:07 -315.146319 0.137554
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}/")