matcalc._adsorption module

Adsorption energy calculations on surfaces.

class AdsorptionCalc(calculator: Calculator | str, *, relax_adsorbate: bool = True, relax_slab: bool = True, relax_bulk: bool = True, fmax: float = 0.1, optimizer: str | Optimizer = 'BFGS', max_steps: int = 500, relax_calc_kwargs: dict[str, Any] | None = None)[source]

Bases: PropCalc

Adsorption energies on surfaces via bulk, slab, adsorbate, and adslab relaxations.

Uses RelaxCalc for geometry optimizations. Attributes mirror constructor arguments plus optional cached bulk state after calc_bulk / calc_adslabs.

Parameters:

  • calculator – ASE calculator or universal model name string.

  • relax_adsorbate – Relax isolated adsorbate in a box when True.

  • relax_slab – Relax clean slab (fixed cell) when True.

  • relax_bulk – Relax bulk with cell when True.

  • fmax – Force tolerance (eV/Å).

  • optimizer – ASE optimizer name or class.

  • max_steps – Max relaxation steps.

  • relax_calc_kwargs – Optional kwargs for RelaxCalc.

_abc_impl = <_abc._abc_data object>[source]
calc(structure: dict[str, Any]) → dict[str, Any][source]
Parameters:

structure – Dict with adslab, slab, adsorbate; optional slab_energy / adsorbate_energy.

Returns:

Dict including adsorption_energy and merged slab/adsorbate fields.

calc_adslabs(adsorbate: Molecule | Atoms, bulk: Structure | Atoms, miller_index: tuple[int, int, int], *, adsorbate_energy: float | None = None, slab_energy: float | None = None, min_slab_size: float = 10.0, min_vacuum_size: float = 20.0, min_area_extent: tuple[float, float] | None = None, inplane_supercell: tuple[int, int] = (1, 1), slab_gen_kwargs: dict[str, Any] | None = None, get_slabs_kwargs: dict[str, Any] | None = None, adsorption_sites: dict[str, Sequence[tuple[float, float]]] | str = 'all', height: float = 0.9, mi_vec: tuple[float, float] | None = None, fixed_height: float = 5, find_adsorption_sites_args: dict[str, Any] | None = None, dry_run: bool = False, **kwargs: dict[str, Any]) → list[dict[str, Any]] | dict[Any, Any][source]
Parameters:

  • adsorbate – Adsorbate species.

  • bulk – Bulk structure (use conventional cell if needed for Miller indices).

  • miller_index – Surface orientation.

  • adsorbate_energy – Optional fixed adsorbate energy.

  • slab_energy – Optional fixed clean-slab energy for all slabs.

  • min_slab_size – Minimum slab thickness (Å).

  • min_vacuum_size – Vacuum thickness (Å).

  • min_area_extent – Minimum in-plane extent (Å); may expand inplane_supercell.

  • inplane_supercell – In-plane supercell factors.

  • slab_gen_kwargs – Kwargs for SlabGenerator.

  • get_slabs_kwargs – Kwargs for SlabGenerator.get_slabs.

  • adsorption_sites – "all", site name string, or custom fractional-coordinate dict.

  • height – Adsorbate height above surface (Å).

  • mi_vec – Optional in-plane vector for AdsorbateSiteFinder.

  • fixed_height – Fix slab atoms below this height (Å) during relaxation.

  • find_adsorption_sites_args – Kwargs for find_adsorption_sites.

  • dry_run – If True, return adslab dicts without calc_many.

  • **kwargs – Forwarded to calc_many.

Returns:

List of per-configuration results, or raw adslab dicts if dry_run.

calc_adsorbate(adsorbate: Molecule | Atoms, adsorbate_energy: float | None = None) → dict[str, Any][source]
Parameters:

  • adsorbate – Adsorbate as molecule or atoms.

  • adsorbate_energy – Optional fixed energy; otherwise from calculator on final geometry.

Returns:

Dict with adsorbate_energy, adsorbate, final_adsorbate.

calc_bulk(bulk: Structure | Atoms, bulk_energy: float | None = None) → dict[str, Any][source]
Parameters:

  • bulk – Bulk pymatgen structure or ASE atoms.

  • bulk_energy – If relax_bulk is False and this is set, used as energy; else relaxed.

Returns:

Dict with final_structure and energy (when available).

calc_slab(slab: Structure | Atoms, slab_energy: float | None = None) → dict[str, Any][source]
Parameters:

  • slab – Slab structure or atoms.

  • slab_energy – Optional total slab energy; if None, taken from calculator.

Returns:

Dict with slab, slab_energy, slab_energy_per_atom, final_slab.