Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

General UMA Workshop

This 1–2 hour tutorial is intended for classrooms, workshops, and guided self-study. It combines several UMA workflows in one linear lesson. The same topics also appear as shorter, task-focused pages elsewhere in the documentation; use Hello World if you only need a concise introduction.

This tutorial walks through representative ways to use UMA. It is best suited to researchers who are new to UMA and already have some familiarity with ASE and molecular simulation.

Before you start / installation

You need to get a HuggingFace account and request access to the UMA models.

You need a Huggingface account, request access to https://huggingface.co/facebook/UMA, and to create a Huggingface token at https://huggingface.co/settings/tokens/ with these permission:

Permissions: Read access to contents of all public gated repos you can access

Then, add the token as an environment variable (using huggingface-cli login:

or you can set the token via HF_TOKEN variable:

Installation process

It may be enough to use pip install fairchem-core. This gets you the latest version on PyPi (https://pypi.org/project/fairchem-core/)

Here we install some sub-packages. This can take 2-5 minutes to run.

fairchem-applications-cattsunami         1.1.2.dev455+gd733f489c
fairchem-core                            2.26.0
fairchem-data-oc                         1.0.3.dev455+gd733f489c
fairchem-data-omat                       0.2.1.dev360+gd733f489c
'2.26.0'

Illustrative examples

These should just run, and are here to show some basic uses.

Spin gap energy - OMOL

This is the difference in energy between a triplet and single ground state for a CH2 radical. This downloads a ~1GB checkpoint the first time you run it.

We don’t set a device here, so we get a warning about using a CPU device. You can ignore that. If a CUDA environment is available, a GPU may be used to speed up the calculations.

WARNING:root:device was not explicitly set, using device='cuda'.
WARNING:root:UMA Nitro cannot serve this request: nitro mode supports only CUDA compute capability 8.x-12.x, not 7.5.
WARNING:root:Now running with nitro=False, execution_mode='umas_fast_gpu' (TF32).
WARNING:root:Running in a reduced-precision mode: some values, such as higher-order derivatives and phonon calculations, will be less accurate. For standard FP32 precision, use inference_settings='high-precision'.
WARNING:root:Model is being compiled. This might take a while the first time.
WARNING:root:Running (unknown commit) with inference settings: multigpu
W1117 18:37:56.233000 14425 site-packages/torch/_logging/_internal.py:1345] [0/0] Profiler record function <class 'torch.autograd.profiler.record_function'> will be ignored
WARNING:root:The UMA fast path (merge_mole + compile) is only available for fixed composition, task, charge, and spin. This is optimized for MD applications. Falling back to a less optimized version for subsequent evaluations. Reason: 'Spin differs: tensor([3]) vs tensor([1], device='cuda:0')'.
Use inference_settings='batch' for heterogeneous batched evaluations.
WARNING:root:Now running with merge_mole=False, compile=False, execution_mode='general' (TF32).
-0.3581800059773741

Example of adsorbate relaxation - OC20

Here we just setup a Cu(100) slab with a CO on it and relax it.

We specify an explicit device in the predictor here, and avoid the warning.

WARNING:root:device was not explicitly set, using device='cuda'.
WARNING:root:UMA Nitro cannot serve this request: nitro mode supports only CUDA compute capability 8.x-12.x, not 7.5.
WARNING:root:Now running with nitro=False, execution_mode='umas_fast_gpu' (TF32).
WARNING:root:Running in a reduced-precision mode: some values, such as higher-order derivatives and phonon calculations, will be less accurate. For standard FP32 precision, use inference_settings='high-precision'.
WARNING:root:Model is being compiled. This might take a while the first time.
WARNING:root:Running (unknown commit) with inference settings: multigpu
       Step     Time          Energy          fmax
LBFGS:    0 18:40:10      -89.681338       11.323901
LBFGS:    1 18:40:10      -92.566008        6.206131
LBFGS:    2 18:40:10      -92.725428        7.225987
LBFGS:    3 18:40:10      -93.076594        3.480319
LBFGS:    4 18:40:10      -93.232397        3.197180
LBFGS:    5 18:40:10      -93.337016        2.257560
LBFGS:    6 18:40:10      -93.578594        1.131646
LBFGS:    7 18:40:10      -93.667720        0.962641
LBFGS:    8 18:40:11      -93.776321        0.594678
LBFGS:    9 18:40:11      -93.855050        0.453709
LBFGS:   10 18:40:11      -93.890289        0.343757
LBFGS:   11 18:40:11      -93.907598        0.323596
LBFGS:   12 18:40:11      -93.933873        0.534406
LBFGS:   13 18:40:11      -93.946599        0.364669
LBFGS:   14 18:40:11      -93.953997        0.148296
LBFGS:   15 18:40:11      -93.958750        0.167810
LBFGS:   16 18:40:11      -93.965451        0.254390
LBFGS:   17 18:40:11      -93.971902        0.264306
LBFGS:   18 18:40:11      -93.976651        0.149611
LBFGS:   19 18:40:11      -93.978217        0.045406
-93.97821708395054

Example bulk relaxation - OMAT

WARNING:root:device was not explicitly set, using device='cuda'.
WARNING:root:UMA Nitro cannot serve this request: nitro mode supports only CUDA compute capability 8.x-12.x, not 7.5.
WARNING:root:Now running with nitro=False, execution_mode='umas_fast_gpu' (TF32).
WARNING:root:Running in a reduced-precision mode: some values, such as higher-order derivatives and phonon calculations, will be less accurate. For standard FP32 precision, use inference_settings='high-precision'.
WARNING:root:Model is being compiled. This might take a while the first time.
WARNING:root:Running (unknown commit) with inference settings: multigpu
W1117 18:41:06.312000 14425 site-packages/torch/_inductor/utils.py:1953] [6/2] Not enough SMs to use max_autotune_gemm mode
      Step     Time          Energy          fmax
FIRE:    0 18:42:02       -8.261836        0.581869
FIRE:    1 18:42:02       -8.268777        0.204165
FIRE:    2 18:42:02       -8.266207        0.459186
FIRE:    3 18:42:02       -8.267597        0.348396
FIRE:    4 18:42:02       -8.269143        0.164888
FIRE:    5 18:42:03       -8.269600        0.035841
[ 3.10657126e-03  3.10658708e-03  3.10669000e-03 -1.05282882e-08
 -6.17142318e-09  1.92560931e-09]

Molecular dynamics - OMOL

WARNING:root:device was not explicitly set, using device='cuda'.
WARNING:root:UMA Nitro cannot serve this request: nitro mode supports only CUDA compute capability 8.x-12.x, not 7.5.
WARNING:root:Now running with nitro=False, execution_mode='umas_fast_gpu' (TF32).
WARNING:root:Running in a reduced-precision mode: some values, such as higher-order derivatives and phonon calculations, will be less accurate. For standard FP32 precision, use inference_settings='high-precision'.
/home/runner/work/_tool/Python/3.12.16/x64/lib/python3.12/site-packages/ase/md/langevin.py:102: FutureWarning: The implementation of `fixcm=True` in `Langevin` does not strictly sample the correct NVT distributions. The deviations are typically small for large systems but can be more pronounced for small systems. Use `fixcm=False` together with `ase.constraints.FixCom`. `fixcm` is deprecated since ASE 3.28.0 and will be removed in a future release.
  warnings.warn(msg, FutureWarning)
WARNING:root:Model is being compiled. This might take a while the first time.
WARNING:root:Running (unknown commit) with inference settings: multigpu
<Figure size 640x480 with 1 Axes>

Catalyst Adsorption energies

The basic approach in computing an adsorption energy is to compute this energy difference:

dH = E_adslab - E_slab - E_ads

We use UMA for two of these energies E_adslab and E_slab. For E_ads We have to do something a little different. The OC20 task is not trained for molecules or molecular fragments. We use atomic energy reference energies instead. These are tabulated below.

The OC20 reference scheme is this reaction:

x CO + (x + y/2 - z) H2 + (z-x) H2O + w/2 N2 + * -> CxHyOzNw*

For this example we have

-H2 + H2O + * -> O*.   "O": -7.204 eV

Where "O": -7.204 is a constant.

To get the desired reaction energy we want we add the formation energy of water. We use either DFT or experimental values for this reaction energy.

1/2O2 + H2 -> H2O

Alternatives to this approach are using DFT to estimate the energy of 1/2 O2, just make sure to use consistent settings with your task. You should not use OMOL for this.

WARNING:root:device was not explicitly set, using device='cuda'.
WARNING:root:UMA Nitro cannot serve this request: nitro mode supports only CUDA compute capability 8.x-12.x, not 7.5.
WARNING:root:Now running with nitro=False, execution_mode='umas_fast_gpu' (TF32).
WARNING:root:Running in a reduced-precision mode: some values, such as higher-order derivatives and phonon calculations, will be less accurate. For standard FP32 precision, use inference_settings='high-precision'.
Relaxing slab
WARNING:root:Model is being compiled. This might take a while the first time.
WARNING:root:Running (unknown commit) with inference settings: multigpu
      Step     Time          Energy          fmax
BFGS:    0 18:42:19     -104.713230        0.695699
BFGS:    1 18:42:19     -104.770832        0.592989
BFGS:    2 18:42:19     -104.910088        0.340089
BFGS:    3 18:42:19     -104.937706        0.411475
BFGS:    4 18:42:19     -105.009225        0.454699
WARNING:root:The UMA fast path (merge_mole + compile) is only available for fixed composition, task, charge, and spin. This is optimized for MD applications. Falling back to a less optimized version for subsequent evaluations. Reason: 'Compositions differ from merged model'.
Use inference_settings='batch' for heterogeneous batched evaluations.
BFGS:    5 18:42:19     -105.068382        0.352799
BFGS:    6 18:42:19     -105.105351        0.173399
BFGS:    7 18:42:19     -105.116032        0.042063

Relaxing adslab
WARNING:root:Now running with merge_mole=False, compile=False, execution_mode='general' (TF32).
      Step     Time          Energy          fmax
BFGS:    0 18:42:26     -110.098583        1.709168
BFGS:    1 18:42:26     -110.275965        0.961389
BFGS:    2 18:42:26     -110.420420        0.724063
BFGS:    3 18:42:26     -110.468239        0.788381
BFGS:    4 18:42:27     -110.569491        0.640713
BFGS:    5 18:42:27     -110.633821        0.473712
BFGS:    6 18:42:27     -110.685972        0.559149
BFGS:    7 18:42:27     -110.731266        0.612389
BFGS:    8 18:42:27     -110.762440        0.457342
BFGS:    9 18:42:28     -110.776662        0.240142
BFGS:   10 18:42:28     -110.780699        0.109505
BFGS:   11 18:42:28     -110.781685        0.093768
BFGS:   12 18:42:28     -110.782524        0.057396
BFGS:   13 18:42:28     -110.783130        0.043505

Now we compute the adsorption energy.

-1.4930980853392763

How did we do? We need a reference point. In the paper below, there is an atomic adsorption energy for O on Pt(111) of about -4.264 eV. This is for the reaction O + * -> O*. To convert this to the dissociative adsorption energy, we have to add the reaction:

1/2 O2 -> O   D = 2.58 eV (expt)

to get a comparable energy of about -1.68 eV. There is about ~0.2 eV difference (we predicted -1.47 eV above, and the reference comparison is -1.68 eV) to account for. The biggest difference is likely due to the differences in exchange-correlation functional. The reference data used the PBE functional, and eSCN was trained on RPBE data. To additional places where there are differences include:

  1. Difference in lattice constant

  2. The reference energy used for the experiment references. These can differ by up to 0.5 eV from comparable DFT calculations.

  3. How many layers are relaxed in the calculation

Some of these differences tend to be systematic, and you can calibrate and correct these, especially if you can augment these with your own DFT calculations.

It is always a good idea to visualize the geometries to make sure they look reasonable.

<Figure size 640x480 with 2 Axes>
<Figure size 640x480 with 2 Axes>

Molecular vibrations

WARNING:root:device was not explicitly set, using device='cuda'.
WARNING:root:UMA Nitro cannot serve this request: nitro mode supports only CUDA compute capability 8.x-12.x, not 7.5.
WARNING:root:Now running with nitro=False, execution_mode='umas_fast_gpu' (TF32).
WARNING:root:Running in a reduced-precision mode: some values, such as higher-order derivatives and phonon calculations, will be less accurate. For standard FP32 precision, use inference_settings='high-precision'.
WARNING:root:Model is being compiled. This might take a while the first time.
WARNING:root:Running (unknown commit) with inference settings: multigpu
      Step     Time          Energy          fmax
BFGS:    0 18:42:40    -2981.068400        1.649247
BFGS:    1 18:42:40    -2980.961398        6.657417
BFGS:    2 18:42:40    -2981.077199        0.215420
BFGS:    3 18:42:40    -2981.077342        0.027023
BFGS:    4 18:42:40    -2981.077345        0.000125
np.True_
---------------------
  #    meV     cm^-1
---------------------
  0    0.0i      0.0i
  1    0.0i      0.0i
  2    0.0       0.0
  3    2.0      16.0
  4    2.0      16.0
  5  309.2    2493.7
---------------------
Zero-point energy: 0.157 eV

Bulk alloy phase behavior

Adapted from https://kitchingroup.cheme.cmu.edu/dft-book/notebooks/04-bulk-systems/10-bulk-reaction-energies.html

We manually compute the formation energy of pure compounds and some alloy compositions to assess stability.

WARNING:root:device was not explicitly set, using device='cuda'.
WARNING:root:UMA Nitro cannot serve this request: nitro mode supports only CUDA compute capability 8.x-12.x, not 7.5.
WARNING:root:Now running with nitro=False, execution_mode='umas_fast_gpu' (TF32).
WARNING:root:Running in a reduced-precision mode: some values, such as higher-order derivatives and phonon calculations, will be less accurate. For standard FP32 precision, use inference_settings='high-precision'.
WARNING:root:Model is being compiled. This might take a while the first time.
WARNING:root:Running (unknown commit) with inference settings: multigpu
      Step     Time          Energy          fmax
FIRE:    0 18:42:49       -3.747320        0.177137
FIRE:    1 18:42:49       -3.748121        0.124314
FIRE:    2 18:42:49       -3.748826        0.030733
-3.748825759754488
WARNING:root:The UMA fast path (merge_mole + compile) is only available for fixed composition, task, charge, and spin. This is optimized for MD applications. Falling back to a less optimized version for subsequent evaluations. Reason: 'Compositions differ from merged model'.
Use inference_settings='batch' for heterogeneous batched evaluations.
WARNING:root:Now running with merge_mole=False, compile=False, execution_mode='general' (TF32).
      Step     Time          Energy          fmax
FIRE:    0 18:42:54       -5.211659        0.162688
FIRE:    1 18:42:54       -5.212260        0.083200
FIRE:    2 18:42:54       -5.212418        0.040824
-5.21241822894234

Alloy formation energies

      Step     Time          Energy          fmax
FIRE:    0 18:42:55       -9.196722        0.119175
FIRE:    1 18:42:55       -9.196860        0.110741
FIRE:    2 18:42:55       -9.197097        0.095550
FIRE:    3 18:42:55       -9.197386        0.076958
FIRE:    4 18:42:55       -9.197713        0.059662
FIRE:    5 18:42:56       -9.198107        0.064213
FIRE:    6 18:42:56       -9.198606        0.066553
FIRE:    7 18:42:56       -9.199217        0.059749
FIRE:    8 18:42:56       -9.199986        0.066176
FIRE:    9 18:42:56       -9.200900        0.083518
FIRE:   10 18:42:56       -9.201997        0.093690
FIRE:   11 18:42:57       -9.203361        0.086998
FIRE:   12 18:42:57       -9.204967        0.062417
FIRE:   13 18:42:57       -9.206711        0.048794
-9.206710743604951
      Step     Time          Energy          fmax
FIRE:    0 18:42:58      -18.140620        0.151727
FIRE:    1 18:42:58      -18.141302        0.136842
FIRE:    2 18:42:58      -18.142405        0.108336
FIRE:    3 18:42:58      -18.143506        0.068689
FIRE:    4 18:42:59      -18.144170        0.021720
-18.144170134143863
-0.24546675490812309
-0.22168215675020697
(-0.023784598157916115, -0.07)

These indicate that cupd-1 and cupd-2 are both more stable than phase separated Cu and Pd, and that cupd-1 is more stable than cupd-2. The absolute formation energies differ from the DFT references, but the relative differences are quite close. The absolute differences could be due to DFT parameter choices (XC, psp, etc.).

Phonon calculation

This takes 4-10 minutes. Adapted from https://docs.ase-lib.org/ase/phonons.html.

Phonons have applications in computing the stability and free energy of solids. See:

  1. https://www.sciencedirect.com/science/article/pii/S1359646215003127

  2. https://iopscience.iop.org/book/mono/978-0-7503-2572-1/chapter/bk978-0-7503-2572-1ch1

WARNING:root:device was not explicitly set, using device='cuda'.
WARNING:root:UMA Nitro cannot serve this request: nitro mode supports only CUDA compute capability 8.x-12.x, not 7.5.
WARNING:root:Now running with nitro=False, execution_mode='umas_fast_gpu' (TF32).
WARNING:root:Running in a reduced-precision mode: some values, such as higher-order derivatives and phonon calculations, will be less accurate. For standard FP32 precision, use inference_settings='high-precision'.
WARNING:root:Model is being compiled. This might take a while the first time.
WARNING:root:Running (unknown commit) with inference settings: multigpu
WARNING, 2 imaginary frequencies at q = ( 0.00,  0.00,  0.00) ; (omega_q = 8.377e-09*i)
WARNING, 2 imaginary frequencies at q = ( 0.00,  0.00,  0.00) ; (omega_q = 8.377e-09*i)
<Figure size 700x400 with 2 Axes>

Transition States (NEBs)

Nudged elastic band calculations are among the most costly calculations we do. UMA makes these quicker!

We explore diffusion of an O adatom from an hcp to an fcc site on Pt(111).

Initial state

WARNING:root:device was not explicitly set, using device='cuda'.
WARNING:root:UMA Nitro cannot serve this request: nitro mode supports only CUDA compute capability 8.x-12.x, not 7.5.
WARNING:root:Now running with nitro=False, execution_mode='umas_fast_gpu' (TF32).
WARNING:root:Running in a reduced-precision mode: some values, such as higher-order derivatives and phonon calculations, will be less accurate. For standard FP32 precision, use inference_settings='high-precision'.
WARNING:root:Model is being compiled. This might take a while the first time.
WARNING:root:Running (unknown commit) with inference settings: multigpu
       Step     Time          Energy          fmax
LBFGS:    0 18:43:10     -141.348182        3.481489
LBFGS:    1 18:43:10     -141.726022        3.485600
LBFGS:    2 18:43:10     -142.966339        2.918311
LBFGS:    3 18:43:10     -143.656315        0.893262
LBFGS:    4 18:43:10     -143.757862        1.265103
LBFGS:    5 18:43:10     -143.833353        0.840169
LBFGS:    6 18:43:10     -143.905840        0.159555
LBFGS:    7 18:43:10     -143.910004        0.142062
LBFGS:    8 18:43:10     -143.916369        0.150817
LBFGS:    9 18:43:10     -143.921726        0.140394
LBFGS:   10 18:43:10     -143.925269        0.078516
LBFGS:   11 18:43:10     -143.927137        0.087056
LBFGS:   12 18:43:10     -143.929041        0.088633
LBFGS:   13 18:43:10     -143.931211        0.092821
LBFGS:   14 18:43:10     -143.932879        0.059824
LBFGS:   15 18:43:10     -143.933607        0.037407
-143.93360714427038

Final state

       Step     Time          Energy          fmax
LBFGS:    0 18:43:10     -141.285771        3.267078
LBFGS:    1 18:43:10     -141.646896        3.244976
LBFGS:    2 18:43:10     -142.858417        2.487966
LBFGS:    3 18:43:10     -143.364172        1.349079
LBFGS:    4 18:43:10     -143.436732        0.979114
LBFGS:    5 18:43:10     -143.570820        0.228624
LBFGS:    6 18:43:10     -143.579444        0.147465
LBFGS:    7 18:43:11     -143.582291        0.129884
LBFGS:    8 18:43:11     -143.585044        0.101469
LBFGS:    9 18:43:11     -143.586902        0.070771
LBFGS:   10 18:43:11     -143.587665        0.051363
LBFGS:   11 18:43:11     -143.588088        0.044090
-143.58808788586327

Setup and relax the band

       Step     Time          Energy          fmax
LBFGS:    0 18:43:11     -143.157643        3.025172
/home/runner/work/_tool/Python/3.12.16/x64/lib/python3.12/site-packages/ase/mep/neb.py:329: UserWarning: The default method has changed from 'aseneb' to 'improvedtangent'. The 'aseneb' method is an unpublished, custom implementation that is not recommended as it frequently results in very poor bands. Please explicitly set method='improvedtangent' to silence this warning, or set method='aseneb' if you strictly require the old behavior (results may vary). See: https://gitlab.com/ase/ase/-/merge_requests/3952
  warnings.warn(
LBFGS:    1 18:43:11     -143.322941        1.449007
LBFGS:    2 18:43:11     -143.372982        0.456676
LBFGS:    3 18:43:11     -143.384761        0.437511
LBFGS:    4 18:43:11     -143.403492        0.475292
LBFGS:    5 18:43:11     -143.420360        0.368622
LBFGS:    6 18:43:11     -143.431519        0.198358
LBFGS:    7 18:43:11     -143.436951        0.168215
LBFGS:    8 18:43:11     -143.438207        0.201683
LBFGS:    9 18:43:12     -143.439911        0.206862
LBFGS:   10 18:43:12     -143.441867        0.184463
LBFGS:   11 18:43:12     -143.443157        0.121590
LBFGS:   12 18:43:12     -143.443825        0.122841
LBFGS:   13 18:43:12     -143.444467        0.120676
LBFGS:   14 18:43:12     -143.445281        0.148219
LBFGS:   15 18:43:12     -143.446108        0.098278
LBFGS:   16 18:43:12     -143.446621        0.064168
LBFGS:   17 18:43:12     -143.446975        0.062965
LBFGS:   18 18:43:12     -143.447431        0.107942
LBFGS:   19 18:43:12     -143.447968        0.096181
LBFGS:   20 18:43:12     -143.448326        0.048748
np.True_
<Figure size 640x480 with 1 Axes>

This could be a good initial guess to initialize an NEB in DFT.

Ideas for things you can do with UMA

Advanced applications

These take a while to run.

AdsorbML

It is so cheap to run these calculations that we can screen a broad range of adsorbate sites and rank them in stability. The AdsorbML approach automates this. This takes quite a while to run here, and we don’t do it in the workshop.

Expert adsorption energies

This tutorial reproduces Fig 6b from the following paper: Zhou, Jing, et al. “Enhanced Catalytic Activity of Bimetallic Ordered Catalysts for Nitrogen Reduction Reaction by Perturbation of Scaling Relations.” ACS Catalysis 134 (2023): 2190-2201 (Zhou & others (2023)).

This takes up to an hour with a GPU, and much longer with a CPU.

CatTsunami

The CatTsunami tutorial is an example of enumerating initial and final states, and computing reaction paths between them with UMA.

Acknowledgments

This tutorial was originally compiled by John Kitchin (CMU) for the NAM29 catalysis tutorial session, using a variety of resources from the FAIR chemistry repository.

References
  1. Musielewicz, J., Wang, X., Tian, T., & Ulissi, Z. (2022). FINETUNA: fine-tuning accelerated molecular simulations. Machine Learning: Science and Technology, 3(3), 03LT01. 10.1088/2632-2153/ac8fe0
  2. Wang, X., Musielewicz, J., Tran, R., Ethirajan, S. K., Fu, X., Mera, H., Kitchin, J. R., Kurchin, R. C., & Ulissi, Z. W. (2024). Generalization of graph-based active learning relaxation strategies across materials. Machine Learning: Science and Technology, 5(2), 025018. 10.1088/2632-2153/ad37f0
  3. Zhou, J., & others. (2023). Enhanced Catalytic Activity of Bimetallic Ordered Catalysts for Nitrogen Reduction Reaction by Perturbation of Scaling Relations. 10.1021/acscatal.2c05877