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.

UMA Catalysis Tutorial

Author: Zack Ulissi (Meta, CMU), with help from AI coding agents / LLMs

Original paper: Bjarne Kreitz et al. JPCC (2021)

Overview

This tutorial demonstrates how to use the Universal Model for Atoms (UMA) machine learning potential to perform comprehensive catalyst surface analysis. We replicate key computational workflows from “Microkinetic Modeling of CO₂ Desorption from Supported Multifaceted Ni Catalysts” by Bjarne Kreitz (now faculty at Georgia Tech!), showing how ML potentials can accelerate computational catalysis research.

Installation and Setup

This tutorial uses a number of helpful open source packages:

Huggingface setups

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:

FAIR Chemistry (UMA) installation

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'

Package imports

First, let’s import all necessary libraries and initialize the UMA-S-1P2P1 predictor:


Loading UMA-S-1P2P1 model...
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'.
✓ Model loaded successfully!

It is somewhat time consuming to run this. We’re going to use a small number of bulks for the testing of this documentation, but otherwise run all of the results for the actual documentation.


Part 1: Bulk Crystal Optimization

Introduction

Before studying surfaces, we need to determine the equilibrium lattice constant of bulk Ni. This is crucial because surface energies and adsorbate binding depend strongly on the underlying lattice parameter.

Theory

For FCC metals like Ni, the lattice constant a defines the unit cell size. The experimental value for Ni is a = 3.524 Å at room temperature. We’ll optimize both atomic positions and the cell volume to find the ML potential’s equilibrium structure.

/tmp/ipykernel_14659/3959847705.py:15: DeprecationWarning: Use FrechetCellFilter for better convergence w.r.t. cell variables.
  ecf = ExpCellFilter(ni_bulk)
Initial lattice constant: 3.52 Å
Number of atoms: 4
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:42:26.665000 14659 site-packages/torch/_logging/_internal.py:1345] [0/0] Profiler record function <class 'torch.autograd.profiler.record_function'> will be ignored

==================================================
Experimental lattice constant: 3.52 Å
Optimized lattice constant:    3.51 Å
Relative error:                0.44%
==================================================

Part 2: Surface Energy Calculations

Introduction

Surface energy (γ) quantifies the thermodynamic cost of creating a surface. It determines surface stability, morphology, and catalytic activity. We’ll calculate γ for four low-index Ni facets: (111), (100), (110), and (211).

Theory

The surface energy is defined as:

γ=Eslab−N⋅Ebulk2A\gamma = \frac{E_{\text{slab}} - N \cdot E_{\text{bulk}}}{2A}

where:

Challenge: Direct calculation suffers from quantum size effects, and if you were doing DFT calculations small numerical errors in the simulation or from the K-point grid sampling can lead to small (but significant) errors in the bulk lattice energy.

Solution: It is fairly common when calculating surface energies to use the bulk energy from a bulk relaxation in the above equation. However, because DFT often has some small numerical noise in the predictions from k-point convergence, this might lead to the wrong surface energy. Instead, two more careful schemes are either:

  1. Calculate the energy of a bulk structure oriented to each slab to maximize cancellation of small numerical errors or

  2. Calculate the energy of multiple slabs at multiple thicknesses and extrapolate to zero thickness. The intercept will be the surface energy, and the slope will be a fitted bulk energy. A benefit of this approach is that it also forces us to check that we have a sufficiently thick slab for a well defined surface energy; if the fit is non-linear we need thicker slabs.

We’ll use the linear extrapolation method here as it’s more likely to work in future DFT studies if you use this code!

Step 1: Setup and Bulk Energy Reference

First, we’ll set up the calculation parameters and get the bulk energy reference:

Bulk energy reference:
  Total energy: -21.97 eV
  Number of atoms: 4
  Energy per atom: -5.492344 eV/atom

Step 2: Generate and Relax Slabs

Now we’ll loop through each facet, generating slabs at three different thicknesses:


============================================================
Calculating Ni(111) surface energy
============================================================

  Thickness: 4 layers
    Atoms: 4
    Energy: -20.67 eV

  Thickness: 6 layers
    Atoms: 6
    Energy: -31.64 eV

  Thickness: 8 layers
    Atoms: 8
    Energy: -42.63 eV

  Linear fit:
    Slope:     -5.490277 eV/atom (cf. bulk -5.492344)
    Intercept: 1.30 eV

  Surface energy:
    γ = 0.121504 eV/Ų = 1.95 J/m²

============================================================
Calculating Ni(100) surface energy
============================================================

  Thickness: 4 layers
    Atoms: 8
    Energy: -42.17 eV

  Thickness: 6 layers
    Atoms: 12
    Energy: -64.14 eV

  Thickness: 8 layers
    Atoms: 16
    Energy: -86.11 eV

  Linear fit:
    Slope:     -5.492716 eV/atom (cf. bulk -5.492344)
    Intercept: 1.77 eV

  Surface energy:
    γ = 0.144095 eV/Ų = 2.31 J/m²

============================================================
Calculating Ni(110) surface energy
============================================================

  Thickness: 4 layers
    Atoms: 10
    Energy: -52.38 eV

  Thickness: 6 layers
    Atoms: 14
    Energy: -74.35 eV

  Thickness: 8 layers
    Atoms: 18
    Energy: -96.32 eV

  Linear fit:
    Slope:     -5.492098 eV/atom (cf. bulk -5.492344)
    Intercept: 2.54 eV

  Surface energy:
    γ = 0.146040 eV/Ų = 2.34 J/m²

============================================================
Calculating Ni(211) surface energy
============================================================

  Thickness: 4 layers
    Atoms: 8
    Energy: -39.66 eV

  Thickness: 6 layers
    Atoms: 12
    Energy: -61.62 eV

  Thickness: 8 layers
    Atoms: 16
    Energy: -83.56 eV

  Linear fit:
    Slope:     -5.486611 eV/atom (cf. bulk -5.492344)
    Intercept: 4.23 eV

  Surface energy:
    γ = 0.140197 eV/Ų = 2.25 J/m²

Step 3: Visualize Linear Fits

Let’s visualize the linear extrapolation for all four facets:

<Figure size 1200x1000 with 4 Axes>

Step 4: Compare with Literature

Finally, let’s compare our calculated surface energies with DFT literature values:


======================================================================
Comparison with DFT Literature (Tran et al., 2016)
======================================================================
Ni(111)        1.95 J/m²  (Lit: 1.92, Δ=1.4%)
Ni(100)        2.31 J/m²  (Lit: 2.21, Δ=4.5%)
Ni(110)        2.34 J/m²  (Lit: 2.29, Δ=2.2%)
Ni(211)        2.25 J/m²  (Lit: 2.24, Δ=0.3%)

Explore on Your Own

  1. Thickness convergence: Add 10 and 12 layer calculations. Is the linear fit still valid?

  2. Constraint effects: Fix the bottom 2 layers during relaxation. How does this affect γ?

  3. Vacuum size: Vary min_vacuum_size from 8 to 15 Å. When does γ converge?

  4. High-index facets: Try (311) or (331) surfaces. Are they more or less stable?

  5. Alternative fitting: Use polynomial (degree 2) instead of linear fit. Does the intercept change?


Part 3: Wulff Construction

Introduction

The Wulff construction predicts the equilibrium shape of a crystalline particle by minimizing total surface energy. This determines the morphology of supported catalyst nanoparticles.

Theory

The Wulff theorem states that at equilibrium, the distance from the particle center to a facet is proportional to its surface energy:

hiγi=constant\frac{h_i}{\gamma_i} = \text{constant}

Facets with lower surface energy have larger areas in the equilibrium shape.

Step 1: Prepare Surface Energies

We’ll use the surface energies calculated in Part 2 to construct the Wulff shape:


Constructing Wulff Shape
==================================================
Using 4 facets:
  (1, 1, 1): 1.95 J/m²
  (1, 0, 0): 2.31 J/m²
  (1, 1, 0): 2.34 J/m²
  (2, 1, 1): 2.25 J/m²

Step 2: Generate Wulff Construction

Now we create the Wulff shape and analyze its properties:


Wulff Shape Properties:
  Volume:          45.85 ų
  Surface area:    66.80 Ų
  Effective radius: 2.22 Å
  Weighted γ:      2.06 J/m²

Facet Area Fractions:
  (1, 1, 1): 66.4%
  (2, 1, 1): 16.3%
  (1, 0, 0): 14.1%
  (1, 1, 0): 3.2%

Step 3: Visualize and Compare

Let’s visualize the Wulff shape and compare with literature:

<Figure size 800x800 with 1 Axes>

Comparison with Paper (Table 2):
  (1, 1, 1):   66.4% (Paper: 69.2%)
  (1, 0, 0):   14.1% (Paper: 21.1%)
  (1, 1, 0):    3.2% (Paper: 5.3%)
  (2, 1, 1):   16.3% (Paper: 4.4%)

Explore on Your Own

  1. Particle size effects: How would including edge/corner energies modify the shape?

  2. Anisotropic strain: Apply 2% compressive strain to the lattice. How does the shape change?

  3. Temperature effects: Surface energies decrease with T. Estimate γ(T) and recompute Wulff shape.

  4. Alloy nanoparticles: Replace some Ni with Cu or Au. How would segregation affect the shape?

  5. Support effects: Some facets interact more strongly with supports. Model this by reducing their γ.


Part 4: H Adsorption Energy with ZPE Correction

Introduction

Hydrogen adsorption is a fundamental step in many catalytic reactions (hydrogenation, dehydrogenation, etc.). We’ll calculate the binding energy with vibrational zero-point energy (ZPE) corrections.

Theory

The adsorption energy is:

Eads=E(slab+H)−E(slab)−12E(H2)E_{\text{ads}} = E(\text{slab+H}) - E(\text{slab}) - \frac{1}{2}E(\text{H}_2)

ZPE correction accounts for quantum vibrational effects:

EadsZPE=Eads+ZPE(H∗)−12ZPE(H2)E_{\text{ads}}^{\text{ZPE}} = E_{\text{ads}} + \text{ZPE}(\text{H}^*) - \frac{1}{2}\text{ZPE}(\text{H}_2)

The ZPE correction is calculated by analyzing the vibrational modes of the molecule/adsorbate.

Step 1: Setup and Relax Clean Slab

First, we create the Ni(111) surface and relax it:

   Created 96 atom slab
   Calculators initialized (ML + D3)

Step 2: Relax Clean Slab

Relax the bare Ni(111) surface as our reference:

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: 'Dataset differs: ['omat'] vs ['oc20']'.
Use inference_settings='batch' for heterogeneous batched evaluations.

1. Relaxing clean Ni(111) slab...
WARNING:root:Now running with merge_mole=False, compile=False, execution_mode='general' (TF32).
/home/runner/work/_tool/Python/3.12.16/x64/lib/python3.12/site-packages/torch_dftd/torch_dftd3_calculator.py:98: UserWarning: Creating a tensor from a list of numpy.ndarrays is extremely slow. Please consider converting the list to a single numpy.ndarray with numpy.array() before converting to a tensor. (Triggered internally at /__w/pytorch/pytorch/torch/csrc/utils/tensor_new.cpp:252.)
  cell: Optional[Tensor] = torch.tensor(
   E(clean): -487.48 eV (ML: -450.74, D3: -36.74)
   ✓ Clean slab relaxed and saved

Step 3: Generate H Adsorption Sites

Use heuristic placement to generate multiple candidate H adsorption sites:


2. Generating 5 H adsorption sites...
   Generated 2 initial configurations
   These include fcc, hcp, bridge, and top sites
/home/runner/work/_tool/Python/3.12.16/x64/lib/python3.12/site-packages/fairchem/data/oc/core/adsorbate.py:79: 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.
  adsorbate_db = safe_pickle_load(fp)

Step 4: Relax All H Configurations

Relax each configuration and identify the most stable site:


3. Relaxing all H adsorption configurations...
   Config 1: -491.53 eV (ML: -454.72, D3: -36.82)
   Config 2: -491.54 eV (ML: -454.72, D3: -36.82)

   ✓ Best site: Config 2, E = -491.54 eV
   Energy spread: 0.00 eV
   This spread indicates the importance of testing multiple sites!

Step 5: Calculate H₂ Reference Energy

We need the H₂ molecule energy as a reference:


4. Calculating H₂ reference energy...
   E(H₂): -6.96 eV (ML: -6.96, D3: -0.00)

Step 6: Compute Adsorption Energy

Calculate the adsorption energy using the formula: E_ads = E(slab+H) - E(slab) - 0.5×E(H₂)


4. Computing Adsorption Energy:
   E_ads = E(slab+H) - E(slab) - 0.5×E(H₂)

   Without D3: -0.50 eV
   With D3:    -0.58 eV
   D3 effect:  -0.08 eV

   → D3 corrections are negligible for H* (small, covalent bonding)

Step 7: Zero-Point Energy (ZPE) Corrections

Calculate vibrational frequencies to get ZPE corrections:


6. Computing ZPE corrections...
   This accounts for quantum vibrational effects
   ZPE(H*):  0.18+0.00j eV
   ZPE(H₂):  0.41+0.00j eV
   E_ads(ZPE): -0.61-0.00j eV

   Creating animations of vibrational modes...
<IPython.core.display.Image object>
0
<Figure size 640x480 with 1 Axes>

Step 8: Visualize and Compare Results

Visualize the best configuration and compare with literature:


7. Visualizing best H* configuration...
Loading...

============================================================
Comparison with Literature:
============================================================
Table 4 (DFT): -0.60 eV (Ni(111), ref H₂)
This work:     -0.61-0.00j eV
Difference:    0.01 eV

Explore on Your Own

  1. Site preference: Identify which site (fcc, hcp, bridge, top) the H prefers. Visualize with view(atoms, viewer='x3d').

  2. Coverage effects: Place 2 H atoms on the slab. How does binding change with separation?

  3. Different facets: Compare H adsorption on (100) and (110) surfaces. Which is strongest?

  4. Subsurface H: Place H below the surface layer. Is it stable?

  5. ZPE uncertainty: How sensitive is E_ads to the vibrational delta parameter (try 0.01, 0.03 Å)?


Part 5: Coverage-Dependent H Adsorption

Introduction

At higher coverages, adsorbate-adsorbate interactions become significant. We’ll study how H binding energy changes from dilute (1 atom) to saturated (full monolayer) coverage.

Theory

The differential adsorption energy at coverage θ is:

Eads(θ)=E(nH∗)−E(∗)−n⋅12E(H2)nE_{\text{ads}}(\theta) = \frac{E(n\text{H}^*) - E(*) - n \cdot \frac{1}{2}E(\text{H}_2)}{n}

For many systems, this varies linearly:

Eads(θ)=Eads(0)+βθE_{\text{ads}}(\theta) = E_{\text{ads}}(0) + \beta \theta

where β quantifies lateral interactions (repulsive if β > 0).

Step 1: Setup Slab and Calculators

Create a larger Ni(111) slab to accommodate multiple adsorbates:

   Created 96 atom slab
   ✓ Calculators initialized

Step 2: Calculate Reference Energies

Get reference energies for clean surface and H₂:


1. Relaxing clean slab...
   E(clean): -487.48 eV

2. Calculating H₂ reference...
   E(H₂): -6.96 eV

Step 3: Set Up Coverage Study

Define the coverages we’ll test (from dilute to nearly 1 ML):


3. Surface sites: 16 (4×4 Ni(111))

   Will test coverages: ['0.06 ML', '0.25 ML', '0.50 ML', '0.75 ML', '1.00 ML']
   This spans from dilute to nearly full monolayer

Step 4: Generate and Relax Configurations at Each Coverage

For each coverage, generate multiple configurations and find the lowest energy:


3. Coverage: 1 H (0.06 ML)
   Generated 2 configurations
/home/runner/work/_tool/Python/3.12.16/x64/lib/python3.12/site-packages/fairchem/data/oc/core/adsorbate.py:79: 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.
  adsorbate_db = safe_pickle_load(fp)
     Config 1: -491.30 eV
     Config 2: -491.54 eV
   → E_ads/H: -0.58 eV
   Visualizing configuration with 1 H atoms...

3. Coverage: 4 H (0.25 ML)
/home/runner/work/_tool/Python/3.12.16/x64/lib/python3.12/site-packages/fairchem/data/oc/core/adsorbate.py:79: 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.
  adsorbate_db = safe_pickle_load(fp)
   Generated 2 configurations
     Config 1: -502.31 eV
     Config 2: -503.55 eV
   → E_ads/H: -0.54 eV
   Visualizing configuration with 4 H atoms...

3. Coverage: 8 H (0.50 ML)
/home/runner/work/_tool/Python/3.12.16/x64/lib/python3.12/site-packages/fairchem/data/oc/core/adsorbate.py:79: 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.
  adsorbate_db = safe_pickle_load(fp)
   Generated 2 configurations
     Config 1: -518.50 eV
     Config 2: -519.50 eV
   → E_ads/H: -0.52 eV
   Visualizing configuration with 8 H atoms...

3. Coverage: 12 H (0.75 ML)
/home/runner/work/_tool/Python/3.12.16/x64/lib/python3.12/site-packages/fairchem/data/oc/core/adsorbate.py:79: 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.
  adsorbate_db = safe_pickle_load(fp)
   Generated 2 configurations
     Config 1: -533.42 eV
     Config 2: -532.32 eV
   → E_ads/H: -0.35 eV
   Visualizing configuration with 12 H atoms...

3. Coverage: 16 H (1.00 ML)
/home/runner/work/_tool/Python/3.12.16/x64/lib/python3.12/site-packages/fairchem/data/oc/core/adsorbate.py:79: 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.
  adsorbate_db = safe_pickle_load(fp)
   Generated 2 configurations
     Config 1: -547.45 eV
     Config 2: -547.08 eV
   → E_ads/H: -0.27 eV
   Visualizing configuration with 16 H atoms...

✓ Completed coverage study: 5 data points

Step 5: Perform Linear Fit

Fit E_ads vs coverage to extract the slope (lateral interaction strength):


4. Performing linear fit to coverage dependence...

============================================================
Linear Fit: E_ads = -0.44 + 0.16θ (eV)
Slope: 15.6 kJ/mol per ML
Paper: 8.7 kJ/mol per ML
============================================================

Step 6: Visualize Coverage Dependence

Create a plot showing how adsorption energy changes with coverage:


5. Plotting coverage dependence...
<Figure size 800x600 with 1 Axes>

✓ Coverage dependence analysis complete!

Explore on Your Own

  1. Non-linear behavior: Use polynomial (degree 2) fit. Is there curvature at high coverage?

  2. Temperature effects: Estimate configurational entropy at each coverage. How does this affect free energy?

  3. Pattern formation: Visualize the lowest-energy configuration at 0.5 ML. Are H atoms ordered?

  4. Other adsorbates: Repeat for O or N. How do lateral interactions compare?

  5. Phase diagrams: At what coverage do you expect phase separation (islands vs uniform)?


Part 6: CO Formation/Dissociation Thermochemistry and Barrier

Introduction

CO dissociation (CO* → C* + O*) is the rate-limiting step in many catalytic processes (Fischer-Tropsch, CO oxidation, etc.). We’ll calculate the reaction energy for C* + O* → CO* and the activation barriers in both directions using the nudged elastic band (NEB) method.

Theory

Step 1: Setup Slab and Calculators

Initialize the Ni(111) surface and calculators:

   Created 96 atom slab
   ✓ Calculators initialized

Step 2: Generate and Relax Final State (CO*)

Find the most stable CO adsorption configuration (this is the product of C+O recombination):


1. Final State: CO* on Ni(111)
   Generating CO adsorption configurations...
   Generated 2 configurations
/home/runner/work/_tool/Python/3.12.16/x64/lib/python3.12/site-packages/fairchem/data/oc/core/adsorbate.py:79: 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.
  adsorbate_db = safe_pickle_load(fp)
     Config 1: E_total = -503.63 eV (RPBE: -466.61, D3: -37.02)
     Config 2: E_total = -503.67 eV (RPBE: -466.64, D3: -37.03)

   → Best CO* (Config 2):
      RPBE:  -466.64 eV
      D3:    -37.03 eV
      Total: -503.67 eV
   ✓ Best CO* structure saved

   Visualizing best CO* structure...
Loading...

Step 3: Generate and Relax Initial State (C* + O*)

Find the most stable configuration for dissociated C and O (reactants):


2. Initial State: C* + O* on Ni(111)
   Generating C+O configurations...
   Generated 2 configurations
/home/runner/work/_tool/Python/3.12.16/x64/lib/python3.12/site-packages/fairchem/data/oc/core/adsorbate.py:79: 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.
  adsorbate_db = safe_pickle_load(fp)
     Config 1: E_total = -502.42 eV (RPBE: -465.36, D3: -37.06, C-O dist: 3.01 Å)
     Config 2: E_total = -502.44 eV (RPBE: -465.38, D3: -37.06, C-O dist: 2.98 Å)

   → Best C*+O* (Config 2):
      RPBE:  -465.38 eV
      D3:    -37.06 eV
      Total: -502.44 eV
   ✓ Best C*+O* structure saved

   Visualizing best C*+O* structure...
Loading...

Step 3b: Calculate C* and O* Energies Separately

Another strategy to calculate the initial energies for *C and *O at very low coverage (without interactions between the two reactants) is to do two separate relaxations.


   Clean slab: E_total = -487.48 eV (RPBE: -450.74, D3: -36.74)

2b. Separate C* and O* Energies:
    Calculating energies in separate unit cells to avoid interactions

   Generating C* configurations...
/home/runner/work/_tool/Python/3.12.16/x64/lib/python3.12/site-packages/fairchem/data/oc/core/adsorbate.py:79: 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.
  adsorbate_db = safe_pickle_load(fp)
     Config 1: E_total = -495.75 eV (RPBE: -458.80, D3: -36.95)
     Config 2: E_total = -495.75 eV (RPBE: -458.80, D3: -36.95)

   → Best C* (Config 1):
      RPBE:  -458.80 eV
      D3:    -36.95 eV
      Total: -495.75 eV

   Visualizing best C* structure...

   Generating O* configurations...
     Config 1: E_total = -494.28 eV (RPBE: -457.42, D3: -36.86)
     Config 2: E_total = -494.69 eV (RPBE: -457.84, D3: -36.85)

   → Best O* (Config 2):
      RPBE:  -457.84 eV
      D3:    -36.85 eV
      Total: -494.69 eV

   Visualizing best O* structure...

   Combined C* + O* (separate calculations):
      RPBE:  -916.64 eV
      D3:    -73.80 eV
      Total: -990.44 eV

   Comparison:
      C*+O* (same cell):  -14.96 eV
      C* + O* (separate): -15.48 eV
      Difference:         0.52 eV
   ✓ Separate C* and O* energies calculated

Step 4: Calculate Reaction Energy with ZPE

Compute the thermochemistry for C* + O* → CO* with ZPE corrections:


3. Reaction Energy (C* + O* → CO*):
   ============================================================

   Electronic Energies:
   Initial (C*+O*): RPBE = -465.38 eV, D3 = -37.06 eV, Total = -502.44 eV
   Final (CO*):     RPBE = -466.64 eV, D3 = -37.03 eV, Total = -503.67 eV

   Reaction Energies (without ZPE):
   ΔE(RPBE only):     -1.26 eV = -121.8 kJ/mol
   ΔE(D3 contrib):    0.03 eV = 2.7 kJ/mol
   ΔE(RPBE+D3):       -1.23 eV = -119.1 kJ/mol

   Computing ZPE for CO*...
   ZPE(CO*): 0.18+0.01j eV (176.5+10.4j meV)

   Computing ZPE for C* and O*...
   ZPE(C*+O*): 0.18+0.00j eV (179.2+0.0j meV)

   Reaction Energy (with ZPE):
   ΔE(electronic):    -1.23 eV = -119.1 kJ/mol
   ΔZPE:              -0.00+0.01j eV = -0.3+1.0j kJ/mol (-2.7+10.4j meV)
   ΔE(total):         -1.24+0.01j eV = -119.4+1.0j kJ/mol

   Summary:
   Without D3, without ZPE: -1.26 eV = -121.8 kJ/mol
   With D3, without ZPE:    -1.23 eV = -119.1 kJ/mol
   With D3, with ZPE:       -1.24+0.01j eV = -119.4+1.0j kJ/mol

   ============================================================

   Comparison with Paper (Table 5):
   Paper (DFT-D3): -142.7 kJ/mol = -1.48 eV
   This work:      -119.4+1.0j kJ/mol = -1.24+0.01j eV
   Difference:     0.24 eV

   ✓ Reaction is exothermic (C+O recombination favorable)

Step 5: Calculate CO Adsorption Energy (Bonus)

Calculate how strongly CO binds to the surface:


4. CO Adsorption Energy ( CO(g) + * → CO*):
   This helps us understand CO binding strength
   CO(g):       E_total = -14.41 eV (RPBE: -14.40, D3: -0.01)
   ZPE(CO(g)):  0.13+0.00j eV
   ZPE(CO*):    0.18+0.01j eV (from Step 4 calculation)

   Electronic Energy Breakdown:
   ΔE(RPBE only) = -1.50 eV
   ΔE(D3 contrib) = -0.28 eV
   ΔE(RPBE+D3) = -1.78 eV

   ZPE Contribution:
   ΔZPE = 0.05+0.01j eV

   Total Adsorption Energy:
   ΔE(total) = -1.73+0.01j eV = -167.2+1.0j kJ/mol

   Summary:
   E_ads(CO) without ZPE = 1.78 eV = 171.6 kJ/mol
   E_ads(CO) with ZPE    = 1.73-0.01j eV = 167.2-1.0j kJ/mol
   → CO binds 1.73 eV stronger than H (2.9x)

Step 6: Find guesses for nearby initial and final states for the reaction

Now that we have an estimate on the reaction energy from the best possible initial and final states, we want to find a transition state (barrier) for this reaction. There are MANY possible ways that we could do this. In this case, we’ll start with the *CO final state and then try and find a nearby local minimal of *C and *O, by fixing the C-O bond distance and finding a nearby local minima. Note that this approach required some insight into what the transition state might look like, and could be considerably more complicated for a reaction that did not involve breaking a single bond.


Finding Transition State Initial and Final States
   Creating initial guess with stretched C-O bond...
   Starting from CO* and stretching the C-O bond...
       Step     Time          Energy          fmax
LBFGS:    0 18:44:55     -466.327224        1.114711
LBFGS:    1 18:44:55     -459.849141       11.172678
LBFGS:    2 18:44:56     -459.928653       10.661246
LBFGS:    3 18:44:56     -460.017295       10.085874
LBFGS:    4 18:44:56     -460.081807        9.661797
LBFGS:    5 18:44:56     -460.129167        9.348041
LBFGS:    6 18:44:56     -460.167583        9.092855
LBFGS:    7 18:44:56     -460.205093        8.844416
LBFGS:    8 18:44:56     -460.258503        8.494629
LBFGS:    9 18:44:56     -460.615144        6.121888
LBFGS:   10 18:44:57     -460.672699        5.735500
LBFGS:   11 18:44:57     -460.743803        5.317399
LBFGS:   12 18:44:57     -460.774227        5.155293
LBFGS:   13 18:44:57     -460.809237        4.965416
LBFGS:   14 18:44:57     -460.847789        4.750046
LBFGS:   15 18:44:57     -460.888001        4.517247
LBFGS:   16 18:44:57     -460.929077        4.269028
LBFGS:   17 18:44:57     -460.970286        4.006867
LBFGS:   18 18:44:58     -461.010802        3.732721
LBFGS:   19 18:44:58     -461.049617        3.450038
LBFGS:   20 18:44:58     -461.085800        3.162897
LBFGS:   21 18:44:58     -461.118462        2.876345
LBFGS:   22 18:44:58     -461.147024        2.595567
LBFGS:   23 18:44:58     -461.171230        2.325365
LBFGS:   24 18:44:58     -461.191078        2.070104
LBFGS:   25 18:44:58     -461.206929        1.832579
LBFGS:   26 18:44:59     -461.219291        1.614385
LBFGS:   27 18:44:59     -461.228884        1.414796
LBFGS:   28 18:44:59     -461.236602        1.229331
LBFGS:   29 18:44:59     -461.244398        1.043486
LBFGS:   30 18:44:59     -461.216528        0.930730
LBFGS:   31 18:44:59     -461.306200        0.652496
LBFGS:   32 18:44:59     -461.305787        0.876944
LBFGS:   33 18:45:00     -461.310956        0.900008
LBFGS:   34 18:45:00     -461.319030        0.886640
LBFGS:   35 18:45:00     -461.331918        0.850988
LBFGS:   36 18:45:00     -461.346252        0.804208
LBFGS:   37 18:45:00     -461.359198        0.748255
LBFGS:   38 18:45:00     -461.370730        0.682390
LBFGS:   39 18:45:00     -461.380504        0.659916
LBFGS:   40 18:45:00     -461.388731        0.705646
LBFGS:   41 18:45:01     -461.396862        0.777774
LBFGS:   42 18:45:01     -461.435951        1.202075
LBFGS:   43 18:45:01     -461.443449        1.192769
LBFGS:   44 18:45:01     -461.453113        1.220259
LBFGS:   45 18:45:01     -461.468033        1.247004
LBFGS:   46 18:45:01     -461.482964        1.258627
LBFGS:   47 18:45:01     -461.506476        1.239172
LBFGS:   48 18:45:01     -461.520007        1.222904
LBFGS:   49 18:45:02     -461.545020        1.154376
LBFGS:   50 18:45:02     -461.556729        1.116986
LBFGS:   51 18:45:02     -461.599752        0.914905
LBFGS:   52 18:45:02     -461.608053        0.868134
LBFGS:   53 18:45:02     -461.632568        0.707473
LBFGS:   54 18:45:02     -461.642401        0.662995
LBFGS:   55 18:45:02     -461.652026        0.619435
LBFGS:   56 18:45:03     -461.660244        0.581262
LBFGS:   57 18:45:03     -461.669099        0.566122
LBFGS:   58 18:45:03     -461.674250        0.910785
LBFGS:   59 18:45:03     -461.733444        0.934140
LBFGS:   60 18:45:03     -461.728103        1.845255
LBFGS:   61 18:45:03     -461.745506        1.598247
LBFGS:   62 18:45:03     -461.752004        1.568711
LBFGS:   63 18:45:03     -461.771310        1.374696
LBFGS:   64 18:45:04     -461.783444        1.341089
LBFGS:   65 18:45:04     -461.794681        1.245565
LBFGS:   66 18:45:04     -461.807637        1.153635
LBFGS:   67 18:45:04     -461.822840        1.061704
LBFGS:   68 18:45:04     -461.838199        1.000658
LBFGS:   69 18:45:04     -461.854883        0.987491
LBFGS:   70 18:45:04     -461.870613        0.931947
LBFGS:   71 18:45:04     -461.887164        0.922467
LBFGS:   72 18:45:05     -461.903761        0.874701
LBFGS:   73 18:45:05     -461.920740        0.878633
LBFGS:   74 18:45:05     -461.938562        0.899557
LBFGS:   75 18:45:05     -461.956448        0.906130
LBFGS:   76 18:45:05     -461.975869        0.931563
LBFGS:   77 18:45:05     -461.995190        0.941528
LBFGS:   78 18:45:05     -462.016633        0.972876
LBFGS:   79 18:45:06     -462.038114        0.987154
LBFGS:   80 18:45:06     -462.062183        1.060242
LBFGS:   81 18:45:06     -462.087497        1.126095
LBFGS:   82 18:45:06     -462.114806        1.220901
LBFGS:   83 18:45:06     -462.147139        1.305632
LBFGS:   84 18:45:06     -462.176323        1.407331
LBFGS:   85 18:45:06     -462.212310        1.493409
LBFGS:   86 18:45:06     -462.238587        1.578768
LBFGS:   87 18:45:07     -462.268001        1.708236
LBFGS:   88 18:45:07     -462.289561        1.856410
LBFGS:   89 18:45:07     -462.314731        1.993140
LBFGS:   90 18:45:07     -462.332768        2.110896
LBFGS:   91 18:45:07     -462.354256        2.216925
LBFGS:   92 18:45:07     -462.369877        2.309811
LBFGS:   93 18:45:07     -462.388775        2.390700
LBFGS:   94 18:45:08     -462.402861        2.463134
LBFGS:   95 18:45:08     -462.419885        2.522411
LBFGS:   96 18:45:08     -462.433177        2.577449
LBFGS:   97 18:45:08     -462.448990        2.618509
LBFGS:   98 18:45:08     -462.462060        2.658026
LBFGS:   99 18:45:08     -462.477199        2.683323
LBFGS:  100 18:45:08     -462.490456        2.708177
LBFGS:  101 18:45:08     -462.505341        2.719576
LBFGS:  102 18:45:09     -462.590223        2.826763
LBFGS:  103 18:45:09     -462.616348        2.289932
LBFGS:  104 18:45:09     -462.659138        2.399692
LBFGS:  105 18:45:09     -462.721289        2.360421
LBFGS:  106 18:45:09     -462.815473        1.928595
LBFGS:  107 18:45:09     -462.880138        1.068437
LBFGS:  108 18:45:09     -462.960659        0.963996
LBFGS:  109 18:45:09     -463.012854        0.585344
LBFGS:  110 18:45:10     -463.041036        0.362218
LBFGS:  111 18:45:10     -463.082437        0.386126
LBFGS:  112 18:45:10     -463.112045        0.261896
LBFGS:  113 18:45:10     -463.095932        0.251463
LBFGS:  114 18:45:10     -463.079539        0.353169
LBFGS:  115 18:45:10     -463.107133        0.530177
LBFGS:  116 18:45:10     -463.120459        0.403115
LBFGS:  117 18:45:11     -463.144560        0.354648
LBFGS:  118 18:45:11     -463.174210        0.338973
LBFGS:  119 18:45:11     -463.163104        0.446550
LBFGS:  120 18:45:11     -463.206715        0.959788
LBFGS:  121 18:45:11     -463.258462        1.819793
LBFGS:  122 18:45:11     -463.305215        2.700298
LBFGS:  123 18:45:11     -463.437835        2.060511
LBFGS:  124 18:45:11     -463.621702        1.166995
LBFGS:  125 18:45:12     -463.598376        1.914604
LBFGS:  126 18:45:12     -463.801165        1.043447
LBFGS:  127 18:45:12     -463.892444        0.946739
LBFGS:  128 18:45:12     -463.984047        0.841633
LBFGS:  129 18:45:12     -464.055965        0.744535
LBFGS:  130 18:45:12     -464.080345        0.551061
LBFGS:  131 18:45:12     -464.117799        0.366469
LBFGS:  132 18:45:13     -464.171883        0.403580
LBFGS:  133 18:45:13     -464.182776        0.963895
LBFGS:  134 18:45:13     -464.217018        0.591282
LBFGS:  135 18:45:13     -464.253451        0.265133
LBFGS:  136 18:45:13     -464.274281        0.257313
LBFGS:  137 18:45:13     -464.259431        0.217608
LBFGS:  138 18:45:13     -464.267006        0.210604
LBFGS:  139 18:45:13     -464.284394        0.171253
LBFGS:  140 18:45:14     -464.293412        0.138550
LBFGS:  141 18:45:14     -464.281679        0.118566
LBFGS:  142 18:45:14     -464.278453        0.100200
LBFGS:  143 18:45:14     -464.283775        0.111153
LBFGS:  144 18:45:14     -464.290966        0.116163
LBFGS:  145 18:45:14     -464.292333        0.096158
LBFGS:  146 18:45:14     -464.294740        0.081117
LBFGS:  147 18:45:14     -464.295147        0.070925
LBFGS:  148 18:45:15     -464.294419        0.077113
LBFGS:  149 18:45:15     -464.293038        0.074849
LBFGS:  150 18:45:15     -464.292421        0.056102
LBFGS:  151 18:45:15     -464.293275        0.048387
LBFGS:  152 18:45:15     -464.295304        0.048948
LBFGS:  153 18:45:15     -464.297505        0.038852
LBFGS:  154 18:45:15     -464.298763        0.031007
LBFGS:  155 18:45:16     -464.298444        0.018532
LBFGS:  156 18:45:16     -464.297420        0.016781
LBFGS:  157 18:45:16     -464.296609        0.012447
LBFGS:  158 18:45:16     -464.296181        0.009503
       Step     Time          Energy          fmax
LBFGS:    0 18:45:16     -464.296181        1.775782
LBFGS:    1 18:45:16     -464.384632        1.752852
LBFGS:    2 18:45:16     -464.868501        1.761694
LBFGS:    3 18:45:16     -464.967877        1.909626
LBFGS:    4 18:45:16     -465.125327        1.743862
LBFGS:    5 18:45:17     -465.246683        1.449508
LBFGS:    6 18:45:17     -465.310073        1.151536
LBFGS:    7 18:45:17     -465.382629        0.735186
LBFGS:    8 18:45:17     -465.423737        0.726104
LBFGS:    9 18:45:17     -465.453398        0.450232
LBFGS:   10 18:45:17     -465.465574        0.307847
LBFGS:   11 18:45:17     -465.470646        0.185729
LBFGS:   12 18:45:18     -465.473266        0.169640
LBFGS:   13 18:45:18     -465.475378        0.147448
LBFGS:   14 18:45:18     -465.477540        0.162849
LBFGS:   15 18:45:18     -465.479017        0.110283
LBFGS:   16 18:45:18     -465.479826        0.064122
LBFGS:   17 18:45:18     -465.480310        0.071604
LBFGS:   18 18:45:18     -465.480827        0.082486
LBFGS:   19 18:45:18     -465.481386        0.071095
LBFGS:   20 18:45:19     -465.481878        0.069977
LBFGS:   21 18:45:19     -465.482230        0.046731
LBFGS:   22 18:45:19     -465.482434        0.040259
LBFGS:   23 18:45:19     -465.482546        0.023688
LBFGS:   24 18:45:19     -465.482616        0.026393
LBFGS:   25 18:45:19     -465.482677        0.022117
LBFGS:   26 18:45:19     -465.482727        0.021774
LBFGS:   27 18:45:19     -465.482760        0.014758
LBFGS:   28 18:45:20     -465.482778        0.011444
LBFGS:   29 18:45:20     -465.482799        0.014106
LBFGS:   30 18:45:20     -465.482813        0.014767
LBFGS:   31 18:45:20     -465.482827        0.010466
LBFGS:   32 18:45:20     -465.482831        0.006187
np.True_

Step 7: Run NEB to Find Activation Barrier

Use the nudged elastic band method to find the minimum energy path:


7. NEB Barrier Calculation (C* + O* → CO*)
   Setting up 7-image NEB chain with TS guess in middle...
   Reaction: C* + O* (initial) → TS → CO* (final)

   Interpolating images...
/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(
   Optimizing NEB path (this may take a while)...

   ✓ NEB converged!

   Forward barrier (C*+O* → CO*): 1.68 eV = 161.8 kJ/mol
   Reverse barrier (CO* → C*+O*): 2.84 eV = 273.6 kJ/mol

   Paper (Table 5): 153 kJ/mol = 1.59 eV 
   Difference: 0.09 eV

Step 8: Visualize NEB Path and Key Structures

Create plots showing the reaction pathway:


   Creating NEB visualization...
/home/runner/work/_tool/Python/3.12.16/x64/lib/python3.12/site-packages/matplotlib/cbook.py:1408: ComplexWarning: Casting complex values to real discards the imaginary part
  return np.asanyarray(x, float)
<Figure size 1000x600 with 1 Axes>

   Creating NEB path animation...
   → Saved as neb_path.gif

   Visualizing initial state (C* + O*)...

   Visualizing transition state...

   Visualizing final state (CO*)...

✓ NEB analysis complete!
<Figure size 640x480 with 1 Axes>

Explore on Your Own

  1. Image convergence: Run with 7 or 9 images. Does the barrier change?

  2. Spring constant: Modify the NEB spring constant. How does this affect convergence?

  3. Alternative paths: Try different initial CO/final C+O configurations. Are there multiple pathways?

  4. Reverse barrier: Calculate E_a(reverse) = E_a(forward) - ΔE. Check Brønsted-Evans-Polanyi relationship.

  5. Diffusion barriers: Compute NEB for C or O diffusion on the surface. How do they compare?


Summary and Best Practices

Key Takeaways

  1. ML Potentials: uma-s-1p2p1 provides ~1000× speedup over DFT with reasonable accuracy

  2. Bulk optimization: Always use the ML-optimized lattice constant for consistency

  3. Surface energies: Linear extrapolation eliminates finite-size effects

  4. Adsorption: Test multiple sites; lowest energy may not be intuitive

  5. Coverage: Lateral interactions become significant above ~0.3 ML

  6. Barriers: NEB requires careful setup but yields full reaction pathway

  1. Optimize Bulk - Determine equilibrium lattice constant

  2. Calculate Surface Energies - Identify stable facets

  3. Wulff Construction - Predict nanoparticle morphology

  4. Low-Coverage Adsorption - Find binding sites and energies

  5. Coverage Study (if coverage-dependent effects are important) - Determine lateral interactions

  6. Reaction Barriers - Calculate activation energies using NEB

  7. Microkinetic Modeling - Predict overall catalytic performance

Accuracy Considerations

PropertyTypical ErrorWhen Critical
Lattice constants1-2%Strain effects, alloys
Surface energies10-20%Nanoparticle shapes
Adsorption energies0.1-0.3 eVThermochemistry
Barriers0.2-0.5 eVKinetics, selectivity

Rule of thumb: Use ML for screening → DFT for validation → Experiment for verification

Further Reading


Appendix: Troubleshooting

Common Issues

Problem: Convergence failures

Problem: NEB fails to find transition state

Problem: Unexpected adsorption energies

Problem: Out of memory

Performance Tips

  1. Use batching: Relax multiple configurations in parallel

  2. Start with DEBUG_MAX_STEPS=50: Get quick results, refine later

  3. Cache bulk energies: Don’t recalculate reference systems

  4. Trajectory analysis: Monitor optimization progress with ASE GUI


Caveats and Pitfalls

1. Task Selection: OMAT vs OC20

Critical choice: Which task_name to use?

Impact: Using wrong task can lead to 0.1-0.3 eV errors in adsorption energies!

2. D3 Dispersion Corrections

Multiple decisions required:

  1. Whether to use D3 at all?

    • Small adsorbates (H, O, N): D3 effect ~0.01-0.05 eV (often negligible)

    • Large molecules (CO, CO₂, aromatics): D3 effect ~0.1-0.3 eV (important!)

    • Physisorption: D3 critical (can change binding from repulsive to attractive)

    • RPBE was originally fit for chemisorption energies without D3 corrections, so adding D3 corrections may actually cause small adsorbates to overbind. However, it probably would be important for larger molecules. It’s relatively uncommon to see RPBE+D3 as a choice in the catalysis literature (compared to PBE+D3, or RPBE, or BEEF-vdW).

  2. Which DFT functional for D3?

    • This tutorial uses method="PBE" consistently for the D3 correction. This is often implied when papers say they use a D3 correction, but the results can be different if use the RPBE parameterizations.

    • Original paper used PBE for bulk/surfaces, RPBE for adsorption. It’s not specified what D3 parameterization they used, but it’s likely PBE.

  3. When to apply D3?

    • End-point correction (used here): Fast, run ML optimization then add D3 energy

    • During optimization: Slower but more accurate geometries

    • Impact: Usually <0.05 eV difference, but can be larger for weak interactions

3. Coverage Dependence Challenges

Non-linearity at high coverage:

Low coverage limit:

4. Periodic Boundary Conditions

UMa requires PBC=True in all directions!

atoms.set_pbc([True, True, True])  # Always required

5. Gas Phase Reference Energies

Tricky cases:

Best practice: Always use stable molecules as references (H₂, not H; H₂O, not OH)

6. Spin Polarization

Key limitation: OC20/UMa does not include spin!

7. Constraint Philosophy

Clean slabs (Part 2): No constraints (both surfaces relax)

Adsorbate slabs (Part 4-6): Bottom layers fixed

Fairchem helper functions: Automatically apply sensible constraints

8. Complex Surface Structures

This tutorial uses low-index facets (111, 100, 110, 211)

Real catalysts have:

9. Slab Thickness and Vacuum

Convergence tests critical but expensive:

10. NEB Convergence

Most computationally expensive part:

Tricks:

  1. Use dimer method to find better TS guess (as shown in Part 6)

  2. Start with coarse convergence (fmax=0.2), refine later

  3. Visualize the path - does it make chemical sense?

  4. Try different spring constants (0.1-1.0 eV/Å)

11. Lattice Constant Source

Consistency is key:

12. Adsorbate Placement

Multiple local minima:

For complex adsorbates: