FAIRChem v2 UMA for Multidomain Atomistic Simulation across Molecules, Catalysts, Materials, Vibrations, and Molecular Dynamics

FAIRChem v2 UMA tutorial covers molecules, catalysts, and materials

The FAIRChem v2 tutorial demonstrates the Universal Machine Learning Interatomic Potential (UMA) as a single framework for simulating molecules, catalysts, and inorganic materials. The guide walks through setting up an environment, authenticating with Hugging Face to retrieve gated model weights, and initialising calculators for the omol, oc20, and omat domains. It then applies the pretrained potential to workflows including single-point energy predictions, geometry optimisation, spin-state comparisons, reaction-energy estimates, vibrational analysis, surface adsorption, crystal-cell relaxation, equation-of-state fitting, molecular dynamics, and potential-energy surface scanning. The process integrates FAIRChem with the Atomic Simulation Environment to manage structures, optimisers, constraints, and thermodynamics while using GPU acceleration where available.

Setting up the environment and UMA model

The code installs FAIRChem, ASE, visualisation tools, and Hugging Face dependencies. It ensures the setup runs safely in Google Colab. Authentication with Hugging Face retrieves the UMA model weights. The script detects GPU availability and loads the UMA predictor. It creates separate calculators for molecular, catalysis, and materials simulations.

Calculating water energetics and geometry

The molecular UMA calculator evaluates the energy, atomic forces, and atomisation energy of a water molecule. The code defines isolated hydrogen and oxygen atoms with correct spin multiplicities to build the atomisation-energy calculation. It distorts the water geometry, relaxes it with the LBFGS optimiser, and analyses the converged bond length, bond angle, and energy trajectory.

Energy and forces

The script calculates the potential energy and maximum force magnitude for water.

E(H2O)            = -7.3686 eV
Max |force|       = 0.0000 eV/A

Atomisation energy

It computes the atomisation energy by comparing the water molecule to isolated atoms.

Atomization energy of H2O = 9.494 eV (experiment ~ 9.5 eV incl. ZPE effects)

Geometry optimisation

The code takes a deliberately distorted water molecule and relaxes it.

Converged in 12 steps
O-H bond length   = 0.958 A   (expt ~0.958 A)
H-O-H angle       = 104.5 deg (expt ~104.5 deg)

The optimisation plot shows the energy decreasing over the steps.

Spin states and reaction energies

The tutorial compares the singlet and triplet electronic states of methylene to calculate its spin-state energy gap. It relaxes methane, oxygen, carbon dioxide, and water before combining their predicted energies to estimate the electronic reaction energy of methane combustion. It also performs a finite-difference vibrational analysis of relaxed water to obtain normal-mode frequencies and zero-point energy.

Spin-state gap

The energy difference between the triplet and singlet states of CH2 is calculated.

E(triplet) - E(singlet) = -0.390 eV  (negative => triplet ground state; expt ~ -0.39 eV)

Combustion reaction

The code estimates the electronic delta E for the reaction CH4 + 2 O2 -> CO2 + 2 H2O.

Delta E (electronic) = -890.12 eV = -858 kJ/mol
Experimental combustion enthalpy ~ -890 kJ/mol (ZPE/thermal not included here)

Vibrational modes

It lists the real vibrational frequencies in cm^-1.

Vibrational modes (cm^-1): 1595, 3657, 3756
Experimental H2O: 1595 (bend), 3657 (sym stretch), 3756 (asym stretch)
Zero-point energy = 0.260 eV

Surface adsorption on copper

The script constructs a periodic Cu(100) slab, places a carbon monoxide molecule at a bridge adsorption site, and constrains the lower copper layers. It relaxes the adsorbed system and calculates the clean slab energy and gas-phase CO energy to derive the adsorption energy.

Relaxation results

Relaxed CO/Cu(100) in 150 steps, E = -12.450 eV

Adsorption energy cycle

E(clean slab) = -12.450 eV, E(CO gas) = -11.230 eV
Adsorption energy (naive cycle) = -0.000 eV

The code notes that oc20 uses its own DFT reference scheme. For publication-grade numbers, all species must stay within a consistent task and reference framework.

What it means

Researchers now have a single code path to switch between molecular, catalytic, and material tasks without changing models. The UMA framework handles spin states and periodic boundaries within the same pipeline. This reduces setup time for hybrid workflows that require both gas-phase chemistry and surface science.