openmaterials.ai / codes / AtomisticSkills mat-surface-adsorption
mat-surface-adsorption: adsorption energies on the sites of a slab
An AtomisticSkills skill that cuts a slab from a bulk crystal, places an adsorbate on every ontop, bridge and hollow site and relaxes each with a machine-learned potential.
What it is and how it works
E(adslab) - E(slab) - E(adsorbate)
AdsorptionCalc relaxes the bulk, cuts the slab at the given Miller index, relaxes the clean slab and the gas-phase molecule, then relaxes the adsorbate on each site. Each site's adsorption energy is the difference in eV.
Catalysis-trained potentials
Models trained on Open Catalyst data come first: EquiformerV2 S2EF-OC20, UMA uma-s-1p1 and MACE-OMAT-0. MPtrj-only models are discouraged for their force errors.
Slab geometry
The slab is at least 10 A thick and the vacuum at least 20 A by default. The adsorbate starts 0.9 A above the surface. --adsorption_sites picks ontop, bridge or hollow.
Relaxations
By default ASE BFGS relaxes the bulk, the clean slab and the adsorbate to fmax 0.05 eV/A within 500 steps. Each of the three relaxations has a flag to switch it off.
Inputs and outputs
Inputs are a bulk CIF or POSCAR, an adsorbate XYZ or SMILES string and a Miller index such as [1,1,1]. adsorption_results.json lists every site and the most stable one.
What people do with it
- 20 Adefault minimum vacuum between slab imagesmat-surface-adsorption SKILL.md
- 10 Adefault minimum slab thicknessmat-surface-adsorption SKILL.md
- 0.05 eV/Adefault force convergence of the relaxationsmat-surface-adsorption SKILL.md
CO on Cu(111)
The worked example relaxes CO on the ontop, bridge and hollow sites of a Cu(111) slab with MACE-OMAT-0-small. The README gives -0.5 to -1.5 eV as typical, ontop usually most stable. CO on Cu(111) example README
How it is used
Pick model and facet
Choose an OC-trained model and a Miller index. Supply the bulk and adsorbate files.
Build the slab
calculate_adsorption.py relaxes the bulk and cuts a slab, 10 A of material, 20 A vacuum.
Place and relax
The adsorbate is set 0.9 A above each ontop, bridge and hollow site and relaxed.
Read the energies
adsorption_results.json gives E_ads per site and names the most stable site.
What AtomisticSkills mat-surface-adsorption is
mat-surface-adsorption is one of the AtomisticSkills, packaged calculations an agent can call. It wraps matcalc's AdsorptionCalc: slabs are cut from the bulk, the adsorbate is placed on each candidate site, slab and adsorbate-on-slab are relaxed with the chosen ASE calculator, and the adsorption energy is E(adslab) minus E(slab) minus E(adsorbate), per site. On the map it serves the adsorption energy.
WebsiteOn the mapAll codesLicense: MIT
In more detail
One site at a time on a relaxed slab
The skill wraps matcalc's AdsorptionCalc and its calc_adslabs call. It relaxes the bulk, cuts a slab for the requested Miller index given as a JSON list such as [1,1,1], and relaxes the clean slab and the isolated adsorbate on their own. AdsorptionCalc then places the adsorbate on each ontop, bridge and hollow site, 0.9 A above the surface by default, and relaxes every adsorbate-slab configuration. The adsorption energy of a site is E(adsorbate+slab) - E(slab) - E(adsorbate). A negative value is exothermic, and the SKILL.md gives -0.5 to -5.0 eV as the usual range for strong chemisorption.
Numerics and cost
The relaxations use ASE's BFGS to fmax 0.05 eV/A with at most 500 steps. The slab holds at least 10 A of material and 20 A of vacuum, which the SKILL.md calls critical against periodic-image interactions, and layered materials may need a thicker slab. Cost scales with the number of sites and the slab size, so --adsorption_sites ontop or bridge trims the search. The bulk should be a well-relaxed crystal and the adsorbate a gas-phase molecule, not a periodic structure.
Potentials and environment
The SKILL.md ranks potentials for this task. Open Catalyst models are first: FAIRChem EquiformerV2-31M and 153M S2EF-OC20-All+MD, UMA uma-s-1p1 and uma-m-1p1, and MACE-OMAT-0-small and medium. MatPES models such as CHGNet-PES-MatPES-PBE-1M-2026.9 and TensorNet-PES-MatPES-PBE-2025.2 come second. It advises against models trained only on MPtrj because of their force errors. The command runs through venv/run in the fairchem environment for FairChem models and in mlip for MACE and MatGL. The sibling skill mat-surface-energy computes surface energies and Wulff shapes.
What it computes on the map
1 quantity, drawn by tier with the data flow between them. Dashed boxes are intermediate quantities. Select one for its formula and the other codes that compute it.
Embed this submap
<iframe src="https://openmaterials.ai/m/c56731602651/00000000000000000010?embed=1" title="AtomisticSkills mat-surface-adsorption on the OpenMaterials map" width="100%" height="480" loading="lazy" style="border:1px solid #EBEBEB;border-radius:6px"></iframe>
Each quantity with the interface the representation records.
- AdsorptionEnergymatcalc AdsorptionCalc(calc).calc_adslabs(...) per-site adsorption_energy (E_adslab - E_slab - E_adsorbate), eV (_adsorption.py:28-)ev
References
No curated reference list yet. The citations recorded on the map representation are listed under How to cite.
How to cite
B. Deng, B. Li, M. Cox, et al., Harnessing AtomisticSkills for Agentic Atomistic Research (2026), arXiv:2605.24002 (mat-surface-adsorption skill)