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 13:56:35 -300.206729 0.046073
LBFGS: 1 13:56:36 -300.207208 0.044109
LBFGS: 2 13:56:36 -300.212885 0.005257
Step Time Energy fmax
LBFGS: 0 13:56:37 -314.863499 1.565261
LBFGS: 1 13:56:37 -314.877970 2.189863
LBFGS: 2 13:56:38 -314.929427 1.335284
LBFGS: 3 13:56:39 -315.089925 1.452585
LBFGS: 4 13:56:39 -315.108187 0.622930
LBFGS: 5 13:56:40 -315.116609 0.280766
LBFGS: 6 13:56:40 -315.119880 0.294298
LBFGS: 7 13:56:41 -315.124883 0.431739
LBFGS: 8 13:56:41 -315.133514 0.614152
LBFGS: 9 13:56:42 -315.138857 0.394160
LBFGS: 10 13:56:42 -315.140805 0.097896
LBFGS: 11 13:56:43 -315.141149 0.131464
LBFGS: 12 13:56:43 -315.142294 0.206022
LBFGS: 13 13:56:44 -315.143886 0.249073
LBFGS: 14 13:56:45 -315.145811 0.227964
LBFGS: 15 13:56:45 -315.147066 0.122312
LBFGS: 16 13:56:46 -315.147578 0.040562
LBFGS: 17 13:56:46 -315.147905 0.051516
LBFGS: 18 13:56:47 -315.148517 0.077320
LBFGS: 19 13:56:47 -315.149131 0.077042
LBFGS: 20 13:56:48 -315.149456 0.030513
Step Time Energy fmax
LBFGS: 0 13:56:49 -314.916207 2.800025
LBFGS: 1 13:56:49 -314.893443 3.561471
LBFGS: 2 13:56:50 -314.969472 1.039453
LBFGS: 3 13:56:50 -314.992897 0.863418
LBFGS: 4 13:56:51 -315.046473 1.800364
LBFGS: 5 13:56:52 -315.103043 1.211532
LBFGS: 6 13:56:52 -315.113031 0.561478
LBFGS: 7 13:56:53 -315.119348 0.343510
LBFGS: 8 13:56:53 -315.122367 0.528589
LBFGS: 9 13:56:54 -315.128872 0.687940
LBFGS: 10 13:56:54 -315.133012 0.483684
LBFGS: 11 13:56:55 -315.135541 0.138828
LBFGS: 12 13:56:55 -315.137151 0.241736
LBFGS: 13 13:56:56 -315.139970 0.453041
LBFGS: 14 13:56:57 -315.144547 0.573879
LBFGS: 15 13:56:57 -315.149124 0.461799
LBFGS: 16 13:56:58 -315.151320 0.189902
LBFGS: 17 13:56:58 -315.152580 0.113240
LBFGS: 18 13:56:59 -315.153672 0.225117
LBFGS: 19 13:56:59 -315.155396 0.355270
LBFGS: 20 13:57:00 -315.157739 0.364328
Step Time Energy fmax
LBFGS: 0 13:57:00 -314.763292 1.805104
LBFGS: 1 13:57:01 -314.764587 2.455956
LBFGS: 2 13:57:02 -314.808443 0.950326
LBFGS: 3 13:57:02 -314.873198 1.495390
LBFGS: 4 13:57:03 -315.025657 1.163692
LBFGS: 5 13:57:03 -315.043048 0.637294
LBFGS: 6 13:57:04 -315.070334 1.231347
LBFGS: 7 13:57:04 -315.080400 1.409612
LBFGS: 8 13:57:05 -315.104607 1.078754
LBFGS: 9 13:57:06 -315.116630 1.397606
LBFGS: 10 13:57:06 -315.128951 0.139912
LBFGS: 11 13:57:07 -315.130435 0.085061
LBFGS: 12 13:57:07 -315.131304 0.076933
LBFGS: 13 13:57:08 -315.132043 0.063040
LBFGS: 14 13:57:09 -315.133445 0.094284
LBFGS: 15 13:57:09 -315.134217 0.088056
LBFGS: 16 13:57:10 -315.134570 0.049295
LBFGS: 17 13:57:10 -315.134725 0.039521
LBFGS: 18 13:57:11 -315.134965 0.051722
LBFGS: 19 13:57:12 -315.135360 0.068707
LBFGS: 20 13:57:12 -315.135766 0.054206
Step Time Energy fmax
LBFGS: 0 13:57:13 -314.866865 2.220352
LBFGS: 1 13:57:13 -314.862470 3.042695
LBFGS: 2 13:57:14 -314.917841 1.107917
LBFGS: 3 13:57:14 -314.962203 1.253191
LBFGS: 4 13:57:15 -315.038727 2.296851
LBFGS: 5 13:57:15 -315.063995 0.984886
LBFGS: 6 13:57:16 -315.073613 0.282314
LBFGS: 7 13:57:17 -315.075444 0.218170
LBFGS: 8 13:57:17 -315.079141 0.536250
LBFGS: 9 13:57:18 -315.084153 0.702063
LBFGS: 10 13:57:18 -315.088371 0.537957
LBFGS: 11 13:57:19 -315.090659 0.184585
LBFGS: 12 13:57:19 -315.091849 0.190492
LBFGS: 13 13:57:20 -315.093458 0.396753
LBFGS: 14 13:57:21 -315.096026 0.516377
LBFGS: 15 13:57:21 -315.098216 0.377489
LBFGS: 16 13:57:22 -315.099176 0.133430
LBFGS: 17 13:57:22 -315.099627 0.092691
LBFGS: 18 13:57:23 -315.100127 0.203232
LBFGS: 19 13:57:23 -315.100899 0.286161
LBFGS: 20 13:57:24 -315.101679 0.246618
Step Time Energy fmax
LBFGS: 0 13:57:25 -314.826849 1.913888
LBFGS: 1 13:57:25 -314.830357 2.630181
LBFGS: 2 13:57:26 -314.879031 1.103465
LBFGS: 3 13:57:26 -314.954080 1.655208
LBFGS: 4 13:57:27 -315.052884 1.750462
LBFGS: 5 13:57:27 -315.070616 0.597040
LBFGS: 6 13:57:28 -315.079430 0.425801
LBFGS: 7 13:57:29 -315.084188 0.774329
LBFGS: 8 13:57:29 -315.093338 1.095935
LBFGS: 9 13:57:30 -315.103776 0.982011
LBFGS: 10 13:57:30 -315.112042 0.316091
LBFGS: 11 13:57:31 -315.113700 0.076469
LBFGS: 12 13:57:32 -315.114382 0.144879
LBFGS: 13 13:57:32 -315.115592 0.213837
LBFGS: 14 13:57:33 -315.116873 0.241427
LBFGS: 15 13:57:33 -315.117905 0.174428
LBFGS: 16 13:57:34 -315.118503 0.083121
LBFGS: 17 13:57:34 -315.118854 0.087885
LBFGS: 18 13:57:34 -315.119352 0.143445
LBFGS: 19 13:57:35 -315.120351 0.216417
LBFGS: 20 13:57:36 -315.121620 0.196629
Step Time Energy fmax
LBFGS: 0 13:57:36 -314.851841 1.981743
LBFGS: 1 13:57:37 -314.854711 2.756767
LBFGS: 2 13:57:37 -314.905253 1.153662
LBFGS: 3 13:57:38 -314.974232 1.622624
LBFGS: 4 13:57:38 -315.057171 2.133789
LBFGS: 5 13:57:39 -315.076445 0.707359
LBFGS: 6 13:57:40 -315.082064 0.317957
LBFGS: 7 13:57:40 -315.084360 0.371273
LBFGS: 8 13:57:41 -315.092301 0.472299
LBFGS: 9 13:57:41 -315.098972 0.418563
LBFGS: 10 13:57:42 -315.102899 0.141621
LBFGS: 11 13:57:43 -315.103801 0.114835
LBFGS: 12 13:57:43 -315.104855 0.217404
LBFGS: 13 13:57:44 -315.106660 0.301046
LBFGS: 14 13:57:44 -315.108458 0.270531
LBFGS: 15 13:57:45 -315.109694 0.150938
LBFGS: 16 13:57:45 -315.110345 0.086832
LBFGS: 17 13:57:46 -315.110996 0.111395
LBFGS: 18 13:57:47 -315.112311 0.195603
LBFGS: 19 13:57:47 -315.114115 0.261307
LBFGS: 20 13:57:48 -315.115621 0.180984
Step Time Energy fmax
LBFGS: 0 13:57:48 -314.781835 1.690653
LBFGS: 1 13:57:49 -314.789058 2.285397
LBFGS: 2 13:57:50 -314.834016 1.065533
LBFGS: 3 13:57:50 -314.955069 1.840420
LBFGS: 4 13:57:51 -314.938158 2.526576
LBFGS: 5 13:57:51 -315.041285 1.219542
LBFGS: 6 13:57:52 -315.069182 0.617947
LBFGS: 7 13:57:53 -315.083784 1.223675
LBFGS: 8 13:57:53 -315.092861 0.794107
LBFGS: 9 13:57:54 -315.111830 0.412962
LBFGS: 10 13:57:54 -315.128464 0.534101
LBFGS: 11 13:57:55 -315.133279 0.539399
LBFGS: 12 13:57:55 -315.137349 0.220400
LBFGS: 13 13:57:56 -315.138417 0.094394
LBFGS: 14 13:57:57 -315.138719 0.093198
LBFGS: 15 13:57:57 -315.139376 0.099908
LBFGS: 16 13:57:57 -315.140228 0.101194
LBFGS: 17 13:57:58 -315.140958 0.075469
LBFGS: 18 13:57:59 -315.141282 0.042101
LBFGS: 19 13:57:59 -315.141452 0.044912
LBFGS: 20 13:58:00 -315.141706 0.066577
Step Time Energy fmax
LBFGS: 0 13:58:00 -314.876033 1.586836
LBFGS: 1 13:58:01 -314.888681 2.276653
LBFGS: 2 13:58:02 -314.937947 1.288270
LBFGS: 3 13:58:02 -315.089271 2.011936
LBFGS: 4 13:58:02 -315.107104 0.569822
LBFGS: 5 13:58:03 -315.110420 0.311918
LBFGS: 6 13:58:04 -315.112087 0.301594
LBFGS: 7 13:58:04 -315.117955 0.248277
LBFGS: 8 13:58:05 -315.123263 0.234827
LBFGS: 9 13:58:05 -315.126474 0.132932
LBFGS: 10 13:58:06 -315.127278 0.120214
LBFGS: 11 13:58:06 -315.128196 0.177389
LBFGS: 12 13:58:07 -315.129905 0.234145
LBFGS: 13 13:58:08 -315.132149 0.228807
LBFGS: 14 13:58:08 -315.134294 0.165446
LBFGS: 15 13:58:09 -315.135562 0.079915
LBFGS: 16 13:58:10 -315.136163 0.066217
LBFGS: 17 13:58:10 -315.136934 0.096586
LBFGS: 18 13:58:11 -315.138137 0.111137
LBFGS: 19 13:58:11 -315.139075 0.068917
LBFGS: 20 13:58:12 -315.139385 0.035795
Step Time Energy fmax
LBFGS: 0 13:58:13 -314.836443 1.764710
LBFGS: 1 13:58:13 -314.845007 2.443023
LBFGS: 2 13:58:14 -314.893457 1.186403
LBFGS: 3 13:58:14 -315.011854 1.977733
LBFGS: 4 13:58:15 -315.063372 1.200329
LBFGS: 5 13:58:15 -315.085958 0.703787
LBFGS: 6 13:58:16 -315.092482 0.313328
LBFGS: 7 13:58:17 -315.098686 0.587823
LBFGS: 8 13:58:17 -315.104091 0.792738
LBFGS: 9 13:58:18 -315.114511 0.893710
LBFGS: 10 13:58:18 -315.120626 0.504780
LBFGS: 11 13:58:19 -315.122777 0.101020
LBFGS: 12 13:58:20 -315.123255 0.147698
LBFGS: 13 13:58:20 -315.124300 0.198392
LBFGS: 14 13:58:21 -315.125516 0.218012
LBFGS: 15 13:58:21 -315.126867 0.190912
LBFGS: 16 13:58:22 -315.127785 0.109040
LBFGS: 17 13:58:23 -315.128342 0.073310
LBFGS: 18 13:58:23 -315.128874 0.119106
LBFGS: 19 13:58:24 -315.129943 0.179701
LBFGS: 20 13:58:24 -315.131300 0.170818
Step Time Energy fmax
LBFGS: 0 13:58:25 -314.834401 2.142807
LBFGS: 1 13:58:26 -314.830622 2.905370
LBFGS: 2 13:58:26 -314.883378 1.040639
LBFGS: 3 13:58:27 -314.929288 1.289909
LBFGS: 4 13:58:27 -315.025673 2.149108
LBFGS: 5 13:58:28 -315.041800 0.932675
LBFGS: 6 13:58:28 -315.061977 0.445063
LBFGS: 7 13:58:29 -315.066559 0.259296
LBFGS: 8 13:58:30 -315.075360 0.831729
LBFGS: 9 13:58:30 -315.081102 0.961646
LBFGS: 10 13:58:31 -315.091300 0.757289
LBFGS: 11 13:58:31 -315.096014 0.240349
LBFGS: 12 13:58:32 -315.097538 0.132715
LBFGS: 13 13:58:32 -315.098760 0.205521
LBFGS: 14 13:58:33 -315.100677 0.247721
LBFGS: 15 13:58:34 -315.102425 0.222555
LBFGS: 16 13:58:34 -315.103498 0.152846
LBFGS: 17 13:58:35 -315.104044 0.051406
LBFGS: 18 13:58:35 -315.104312 0.069288
LBFGS: 19 13:58:36 -315.104670 0.119310
LBFGS: 20 13:58:36 -315.105220 0.134800
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}/")