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
bulk_src_id = "mp-30"
# adsorbate smiles string from our database https://github.com/facebookresearch/fairchem/blob/main/src/fairchem/data/oc/databases/pkls/adsorbates.pkl
adsorbate = "*CO"
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.12/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-1p1")
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'.
WARNING:root:If 'dataset_list' is provided in the config, the code assumes that each dataset maps to itself. Please use 'dataset_mapping' as 'dataset_list' is deprecated and will be removed in the future.
Step Time Energy fmax
LBFGS: 0 22:51:42 -300.219297 0.047121
LBFGS: 1 22:51:43 -300.219791 0.045100
LBFGS: 2 22:51:43 -300.225582 0.004432
Step Time Energy fmax
LBFGS: 0 22:51:44 -314.875870 1.029567
LBFGS: 1 22:51:44 -314.899597 1.511838
LBFGS: 2 22:51:45 -315.003584 1.959577
LBFGS: 3 22:51:45 -315.041725 1.910408
LBFGS: 4 22:51:46 -315.112925 0.936429
LBFGS: 5 22:51:46 -315.135216 0.443214
LBFGS: 6 22:51:47 -315.141457 0.325574
LBFGS: 7 22:51:47 -315.144261 0.289145
LBFGS: 8 22:51:47 -315.164418 0.642094
LBFGS: 9 22:51:48 -315.166519 0.252848
LBFGS: 10 22:51:48 -315.167727 0.150237
LBFGS: 11 22:51:49 -315.168249 0.199972
LBFGS: 12 22:51:49 -315.169234 0.240345
LBFGS: 13 22:51:50 -315.170826 0.261048
LBFGS: 14 22:51:50 -315.173121 0.243383
LBFGS: 15 22:51:51 -315.175024 0.160427
LBFGS: 16 22:51:52 -315.175810 0.038298
LBFGS: 17 22:51:52 -315.176005 0.040120
LBFGS: 18 22:51:53 -315.176275 0.069772
LBFGS: 19 22:51:53 -315.176689 0.082776
LBFGS: 20 22:51:54 -315.177088 0.053944
Step Time Energy fmax
LBFGS: 0 22:51:54 -314.824583 0.782865
LBFGS: 1 22:51:55 -314.846281 0.941104
LBFGS: 2 22:51:55 -315.035906 1.531106
LBFGS: 3 22:51:56 -315.037565 1.148051
LBFGS: 4 22:51:57 -315.075606 0.528424
LBFGS: 5 22:51:57 -315.086935 0.742471
LBFGS: 6 22:51:58 -315.096869 0.666481
LBFGS: 7 22:51:58 -315.133932 1.836667
LBFGS: 8 22:51:59 -315.146487 0.275038
LBFGS: 9 22:51:59 -315.151121 0.255954
LBFGS: 10 22:52:00 -315.154579 0.389222
LBFGS: 11 22:52:00 -315.155798 0.148344
LBFGS: 12 22:52:01 -315.156636 0.140770
LBFGS: 13 22:52:01 -315.157149 0.203164
LBFGS: 14 22:52:02 -315.158226 0.240615
LBFGS: 15 22:52:02 -315.159006 0.184046
LBFGS: 16 22:52:03 -315.159468 0.072373
LBFGS: 17 22:52:04 -315.159647 0.056298
LBFGS: 18 22:52:04 -315.159872 0.109376
LBFGS: 19 22:52:05 -315.160303 0.167265
LBFGS: 20 22:52:05 -315.160830 0.160661
Step Time Energy fmax
LBFGS: 0 22:52:06 -314.859926 0.788446
LBFGS: 1 22:52:06 -314.880488 0.752234
LBFGS: 2 22:52:07 -314.954453 3.938595
LBFGS: 3 22:52:07 -315.025467 0.628916
LBFGS: 4 22:52:08 -315.063662 0.455175
LBFGS: 5 22:52:08 -315.075001 0.531815
LBFGS: 6 22:52:09 -315.080734 0.358239
LBFGS: 7 22:52:09 -315.092261 0.408836
LBFGS: 8 22:52:09 -315.111460 0.405735
LBFGS: 9 22:52:10 -315.119332 0.490629
LBFGS: 10 22:52:10 -315.122185 0.244302
LBFGS: 11 22:52:11 -315.124573 0.129763
LBFGS: 12 22:52:11 -315.126232 0.124593
LBFGS: 13 22:52:12 -315.130064 0.213179
LBFGS: 14 22:52:12 -315.131504 0.228381
LBFGS: 15 22:52:13 -315.132193 0.138438
LBFGS: 16 22:52:14 -315.132727 0.061598
LBFGS: 17 22:52:14 -315.133026 0.111626
LBFGS: 18 22:52:15 -315.133389 0.138147
LBFGS: 19 22:52:15 -315.133835 0.131552
LBFGS: 20 22:52:16 -315.134167 0.071576
Step Time Energy fmax
LBFGS: 0 22:52:16 -314.891709 0.911087
LBFGS: 1 22:52:17 -314.913838 0.883240
LBFGS: 2 22:52:17 -315.057900 1.842381
LBFGS: 3 22:52:18 -315.076264 0.493429
LBFGS: 4 22:52:18 -315.092787 0.250695
LBFGS: 5 22:52:19 -315.096417 0.277857
LBFGS: 6 22:52:19 -315.099686 0.306876
LBFGS: 7 22:52:20 -315.115788 0.277558
LBFGS: 8 22:52:20 -315.119728 0.160570
LBFGS: 9 22:52:21 -315.121102 0.125198
LBFGS: 10 22:52:21 -315.122811 0.171014
LBFGS: 11 22:52:22 -315.125548 0.200426
LBFGS: 12 22:52:22 -315.127861 0.149882
LBFGS: 13 22:52:23 -315.129212 0.077575
LBFGS: 14 22:52:24 -315.129669 0.060064
LBFGS: 15 22:52:24 -315.130047 0.067620
LBFGS: 16 22:52:25 -315.130793 0.098195
LBFGS: 17 22:52:25 -315.131550 0.086168
LBFGS: 18 22:52:26 -315.131977 0.043346
LBFGS: 19 22:52:26 -315.132134 0.040532
LBFGS: 20 22:52:27 -315.132265 0.040748
Step Time Energy fmax
LBFGS: 0 22:52:27 -314.888771 0.918074
LBFGS: 1 22:52:28 -314.911042 0.891599
LBFGS: 2 22:52:28 -315.050099 2.265873
LBFGS: 3 22:52:29 -315.074698 0.404909
LBFGS: 4 22:52:29 -315.092703 0.260672
LBFGS: 5 22:52:30 -315.096815 0.291531
LBFGS: 6 22:52:30 -315.099997 0.309245
LBFGS: 7 22:52:31 -315.117367 0.230315
LBFGS: 8 22:52:31 -315.119951 0.138703
LBFGS: 9 22:52:31 -315.120938 0.116544
LBFGS: 10 22:52:32 -315.123200 0.139803
LBFGS: 11 22:52:32 -315.125525 0.138169
LBFGS: 12 22:52:33 -315.127468 0.103954
LBFGS: 13 22:52:33 -315.128422 0.079286
LBFGS: 14 22:52:34 -315.128901 0.063893
LBFGS: 15 22:52:35 -315.129593 0.102570
LBFGS: 16 22:52:35 -315.130703 0.122446
LBFGS: 17 22:52:36 -315.131716 0.086367
LBFGS: 18 22:52:36 -315.132136 0.046753
LBFGS: 19 22:52:37 -315.132282 0.033374
LBFGS: 20 22:52:37 -315.132429 0.046531
Step Time Energy fmax
LBFGS: 0 22:52:38 -314.850722 1.050066
LBFGS: 1 22:52:38 -314.865523 1.131137
LBFGS: 2 22:52:39 -314.921242 1.640314
LBFGS: 3 22:52:39 -314.861296 5.018714
LBFGS: 4 22:52:40 -315.016573 0.830606
LBFGS: 5 22:52:41 -315.044842 0.673702
LBFGS: 6 22:52:41 -315.065203 0.689759
LBFGS: 7 22:52:42 -315.073990 0.536683
LBFGS: 8 22:52:42 -315.097229 0.605319
LBFGS: 9 22:52:43 -315.116316 0.270778
LBFGS: 10 22:52:43 -315.118336 0.245546
LBFGS: 11 22:52:44 -315.119898 0.198760
LBFGS: 12 22:52:44 -315.129963 0.114673
LBFGS: 13 22:52:45 -315.130890 0.133743
LBFGS: 14 22:52:45 -315.132059 0.131251
LBFGS: 15 22:52:45 -315.133559 0.107272
LBFGS: 16 22:52:46 -315.135788 0.109429
LBFGS: 17 22:52:46 -315.137707 0.157646
LBFGS: 18 22:52:47 -315.139208 0.142755
LBFGS: 19 22:52:47 -315.140488 0.130599
LBFGS: 20 22:52:48 -315.142378 0.153283
Step Time Energy fmax
LBFGS: 0 22:52:48 -314.810774 0.805314
LBFGS: 1 22:52:49 -314.832915 1.171548
LBFGS: 2 22:52:50 -315.034947 1.709020
LBFGS: 3 22:52:50 -314.607073 7.416512
LBFGS: 4 22:52:51 -315.074505 0.855954
LBFGS: 5 22:52:51 -315.092192 0.561274
LBFGS: 6 22:52:52 -315.111201 1.355091
LBFGS: 7 22:52:52 -315.120768 0.774127
LBFGS: 8 22:52:53 -315.138880 0.295009
LBFGS: 9 22:52:53 -315.158432 0.163095
LBFGS: 10 22:52:54 -315.161949 0.467721
LBFGS: 11 22:52:54 -315.163149 0.249076
LBFGS: 12 22:52:55 -315.164534 0.157761
LBFGS: 13 22:52:55 -315.164887 0.164623
LBFGS: 14 22:52:56 -315.165877 0.146893
LBFGS: 15 22:52:57 -315.166891 0.121457
LBFGS: 16 22:52:57 -315.167845 0.077807
LBFGS: 17 22:52:58 -315.168221 0.037912
LBFGS: 18 22:52:58 -315.168392 0.049868
LBFGS: 19 22:52:59 -315.168642 0.071750
LBFGS: 20 22:52:59 -315.169068 0.081483
Step Time Energy fmax
LBFGS: 0 22:53:00 -314.782433 0.779718
LBFGS: 1 22:53:00 -314.802191 0.964608
LBFGS: 2 22:53:01 -315.037829 1.331460
LBFGS: 3 22:53:01 -315.041756 0.714052
LBFGS: 4 22:53:02 -315.063637 0.560097
LBFGS: 5 22:53:02 -315.095814 1.749602
LBFGS: 6 22:53:02 -315.121365 1.138016
LBFGS: 7 22:53:03 -315.151173 1.020131
LBFGS: 8 22:53:04 -315.155478 0.342587
LBFGS: 9 22:53:04 -315.158432 0.165953
LBFGS: 10 22:53:05 -315.160610 0.272643
LBFGS: 11 22:53:05 -315.161677 0.110341
LBFGS: 12 22:53:06 -315.162344 0.099951
LBFGS: 13 22:53:06 -315.162819 0.170397
LBFGS: 14 22:53:07 -315.163729 0.206172
LBFGS: 15 22:53:07 -315.164347 0.140601
LBFGS: 16 22:53:08 -315.164650 0.045382
LBFGS: 17 22:53:09 -315.164780 0.047260
LBFGS: 18 22:53:09 -315.164952 0.095813
LBFGS: 19 22:53:10 -315.165234 0.133001
LBFGS: 20 22:53:10 -315.165537 0.109608
Step Time Energy fmax
LBFGS: 0 22:53:11 -314.821875 0.776715
LBFGS: 1 22:53:11 -314.840695 0.701813
LBFGS: 2 22:53:12 -314.941056 3.910818
LBFGS: 3 22:53:12 -314.990565 0.782847
LBFGS: 4 22:53:13 -315.033682 0.530385
LBFGS: 5 22:53:13 -315.047259 0.972922
LBFGS: 6 22:53:14 -315.057808 0.499595
LBFGS: 7 22:53:14 -315.076897 0.434802
LBFGS: 8 22:53:15 -315.114308 0.288809
LBFGS: 9 22:53:16 -315.122038 1.066084
LBFGS: 10 22:53:16 -315.128573 0.402524
LBFGS: 11 22:53:17 -315.132994 0.189420
LBFGS: 12 22:53:17 -315.136488 0.184510
LBFGS: 13 22:53:18 -315.140211 0.154199
LBFGS: 14 22:53:18 -315.142481 0.254029
LBFGS: 15 22:53:19 -315.144070 0.238729
LBFGS: 16 22:53:19 -315.145771 0.166779
LBFGS: 17 22:53:20 -315.146553 0.054256
LBFGS: 18 22:53:20 -315.146786 0.063818
LBFGS: 19 22:53:21 -315.147091 0.108978
LBFGS: 20 22:53:21 -315.147541 0.125081
Step Time Energy fmax
LBFGS: 0 22:53:22 -314.979639 1.283635
LBFGS: 1 22:53:22 -314.993696 1.613014
LBFGS: 2 22:53:23 -315.028839 1.216126
LBFGS: 3 22:53:23 -315.100565 1.099435
LBFGS: 4 22:53:24 -315.138541 0.375862
LBFGS: 5 22:53:24 -315.145178 0.209497
LBFGS: 6 22:53:25 -315.148506 0.275165
LBFGS: 7 22:53:25 -315.152619 0.305963
LBFGS: 8 22:53:26 -315.161030 0.267148
LBFGS: 9 22:53:26 -315.165676 0.202223
LBFGS: 10 22:53:27 -315.168221 0.155257
LBFGS: 11 22:53:27 -315.169760 0.157981
LBFGS: 12 22:53:28 -315.172718 0.168126
LBFGS: 13 22:53:28 -315.175829 0.152707
LBFGS: 14 22:53:28 -315.177902 0.094191
LBFGS: 15 22:53:29 -315.178856 0.056336
LBFGS: 16 22:53:29 -315.179272 0.066167
LBFGS: 17 22:53:30 -315.179672 0.057716
LBFGS: 18 22:53:30 -315.180254 0.056545
LBFGS: 19 22:53:31 -315.180697 0.045035
LBFGS: 20 22:53:31 -315.180884 0.037520
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}/")