Mat Surface Adsorption

Surface Adsorption Skill

This skill provides tools for calculating adsorption energies ($E_{ads}$) of molecules on crystalline surfaces using Machine Learning Interatomic Potentials (MLIPs).

Goal

To calculate the adsorption energy for a given adsorbate-surface combination, defined as:

$$E_{ads} = E_{adsorbate+slab} - E_{slab} - E_{adsorbate}$$

where:

• $E_{adsorbate+slab}$ is the total energy of the adsorbate adsorbed on the surface
• $E_{slab}$ is the energy of the clean slab
• $E_{adsorbate}$ is the energy of the isolated adsorbate molecule

The skill uses MatCalc's AdsorptionCalc to automate the full workflow: bulk relaxation, slab generation, adsorbate relaxation, site identification, and energy calculations.

Prerequisites

• The appropriate MLIP wrapper must be available (MACEWrapper, MatGLWrapper, or FAIRCHEMWrapper)
• matcalc, pymatgen, and ase are included in the mlip and fairchem environments
• A bulk crystalline structure file (CIF, POSCAR, etc.)
• An adsorbate molecule structure file (XYZ, CIF) or SMILES string

Choosing a Foundation Potential

Adsorption energy calculations require accurate prediction of both energies and forces, particularly for the adsorbate-surface interaction. Models trained on Open Catalyst datasets are especially recommended as they were specifically designed for catalysis and surface chemistry.

[!IMPORTANT] Recommended models (in order of preference):

1. Open Catalyst trained models (BEST for surface adsorption):
   • FAIRChem: EquiformerV2-31M-S2EF-OC20-All+MD, EquiformerV2-153M-S2EF-OC20-All+MD
   • FAIRChem UMA: uma-s-1p1, uma-m-1p1 (universal, includes OC20/OC25 data)
   • MACE-OMAT: MACE-OMAT-0-small, MACE-OMAT-0-medium (trained on OC datasets)
2. MatPES trained models (Good for general surfaces):
   • CHGNet-PES-MatPES-PBE-1M-2026.9
   • M3GNet-MatPES-PBE-v2025.1-PES
   • MACE-MatPES-PBE-0
3. Avoid MPtrj-only models: Models trained primarily on the MPtrj dataset may suffer from force prediction issues critical for adsorption.

Why Open Catalyst models? The OC20, OC22, and OC25 datasets contain millions of adsorbate-surface configurations specifically for catalysis, making these models highly accurate for adsorption energies and barriers.

Refer to the foundation-potentials skill for detailed guidance on model selection.

Calculation Workflow

To calculate adsorption energies, use the calculate_adsorption.py script:

${CLAUDE_SKILL_DIR}/../../venv/run fairchem python ${CLAUDE_SKILL_DIR}/scripts/calculate_adsorption.py \
    --bulk path/to/bulk_structure.cif \
    --adsorbate path/to/adsorbate.xyz \
    --miller_index '[1,1,1]' \
    --model_type fairchem \
    --model_name EquiformerV2-31M-S2EF-OC20-All+MD \
    --fmax 0.05 \
    --output_dir research/my_folder/adsorption

Key Parameters

• --bulk: Path to bulk structure file (CIF, POSCAR, etc.)
• --adsorbate: Path to adsorbate molecule file (XYZ, CIF) or SMILES string
• --miller_index: Miller index for the surface as JSON list (e.g., '[1,1,1]', '[1,0,0]')
• --model_type: MLIP model type (mace, matgl, or fairchem)
• --model_name: Specific model name (optional, uses defaults if not provided)

Optional Settings

Relaxation control:

• --relax_bulk / --no_relax_bulk: Control bulk structure relaxation (default: True)
• --relax_slab / --no_relax_slab: Control clean slab relaxation (default: True)
• --relax_adsorbate / --no_relax_adsorbate: Control adsorbate molecule relaxation (default: True)

Convergence:

• --fmax: Force convergence criterion in eV/Å (default: 0.05)
• --optimizer: ASE optimizer (default: BFGS)
• --max_steps: Maximum optimization steps (default: 500)

Slab generation:

• --min_slab_size: Minimum slab thickness in Å (default: 10.0)
• --min_vacuum_size: Minimum vacuum layer in Å (default: 20.0)
• --adsorption_sites: Sites to consider: 'all', 'ontop', 'bridge', 'hollow' (default: all)
• --height: Initial adsorbate height above surface in Å (default: 0.9)

Output Files

The calculation generates the following files in the output directory:

• adsorption_results.json: Complete summary including:
  • Adsorption energies for all identified sites
  • Most stable adsorption site and energy
  • Calculation settings and metadata
  • Individual site energies (adslab, slab, adsorbate)