core.components.calculate.recipes.adsorbml

core.components.calculate.recipes.adsorbml#

Copyright (c) Meta Platforms, Inc. and affiliates.

This source code is licensed under the MIT license found in the LICENSE file in the root directory of this source tree.

Functions#

relax_job(initial_atoms, calc, optimizer_cls, fmax, steps)

adsorb_ml_pipeline(slab, adsorbates_kwargs, ...[, ...])

Run a machine learning-based pipeline for adsorbate-slab systems.

ocp_adslab_generator(→ list[ase.atoms.Atoms])

Generate adsorbate-slab configurations.

reference_adslab_energies(→ list[dict])

Reference adsorbate-slab energies to atomic and slab energies.

filter_sort_select_adslabs(→ list[dict])

Filter, sort, and select adsorbate-slab configurations based on anomalies and energy.

detect_anomaly(→ list[Literal[, , , ]])

Detect anomalies between initial and final atomic structures.

run_adsorbml(slab, adsorbate, calculator, optimizer_cls)

Run the AdsorbML pipeline for a given slab and adsorbate using a pretrained ML model.

Module Contents#

core.components.calculate.recipes.adsorbml.relax_job(initial_atoms, calc, optimizer_cls, fmax, steps)#
core.components.calculate.recipes.adsorbml.adsorb_ml_pipeline(slab: fairchem.data.oc.core.slab.Slab, adsorbates_kwargs: dict[str, Any], multiple_adsorbate_slab_config_kwargs: dict[str, Any], ml_slab_adslab_relax_job: collections.abc.Callable[Ellipsis, Any], reference_ml_energies: bool = True, atomic_reference_energies: dict | None = None, relaxed_slab_atoms: ase.atoms.Atoms = None, place_on_relaxed_slab: bool = False)#

Run a machine learning-based pipeline for adsorbate-slab systems.

  1. Relax slab using ML

  2. Generate trial adsorbate-slab configurations for the relaxed slab

  3. Relax adsorbate-slab configurations using ML

  4. Validate slab and adsorbate-slab configurations (check for anomalies like dissociations))

  5. Reference the energies to gas phase if needed (eg using a total energy ML model)

Parameters:

  • slab (Slab) – The slab structure to which adsorbates will be added.

  • adsorbates_kwargs (dict[str,Any]) – Keyword arguments for generating adsorbate configurations.

  • multiple_adsorbate_slab_config_kwargs (dict[str, Any]) – Keyword arguments for generating multiple adsorbate-slab configurations.

  • ml_slab_adslab_relax_job (Job) – Job for relaxing slab and adsorbate-slab configurations using ML.

  • reference_ml_energies (bool, optional) – Whether to reference ML energies to gas phase, by default False.

  • atomic_reference_energies (AtomicReferenceEnergies, optional) – Atomic reference energies for referencing, by default None.

  • relaxed_slab_atoms (ase.Atoms, optional) – DFT Relaxed slab atoms for anomaly detection for adsorption energy models, by default None.

  • place_on_relaxed_slab (bool, optional) – Whether to place adsorbates on the relaxed slab or initial unrelaxed slab, by default False.

Returns:

Dictionary containing the slab, ML-relaxed adsorbate-slab configurations, detected anomalies.

Return type:

dict

core.components.calculate.recipes.adsorbml.ocp_adslab_generator(slab: fairchem.data.oc.core.slab.Slab | ase.atoms.Atoms, adsorbates_kwargs: list[dict[str, Any]] | None = None, multiple_adsorbate_slab_config_kwargs: dict[str, Any] | None = None) → list[ase.atoms.Atoms]#

Generate adsorbate-slab configurations.

Parameters:

  • slab (Slab | Atoms) – The slab structure.

  • adsorbates_kwargs (list[dict[str,Any]], optional) – List of keyword arguments for generating adsorbates, by default None.

  • multiple_adsorbate_slab_config_kwargs (dict[str,Any], optional) – Keyword arguments for generating multiple adsorbate-slab configurations, by default None.

Returns:

List of generated adsorbate-slab configurations.

Return type:

list[Atoms]

core.components.calculate.recipes.adsorbml.reference_adslab_energies(adslab_results: list[dict], slab_result: dict, atomic_energies: dict) → list[dict]#

Reference adsorbate-slab energies to atomic and slab energies.

Parameters:

  • adslab_results (list[dict[str, Any]]) – List of adsorbate-slab results.

  • slab_result (dict) – Result of the slab calculation.

  • atomic_energies (AtomicReferenceEnergies | None) – Dictionary of atomic energies.

Returns:

List of adsorbate-slab results with referenced energies.

Return type:

list[dict[str, Any]]

core.components.calculate.recipes.adsorbml.filter_sort_select_adslabs(adslab_results: list[dict], adslab_anomalies_list: list[list[str]]) → list[dict]#

Filter, sort, and select adsorbate-slab configurations based on anomalies and energy.

Parameters:

  • adslab_results (list[dict]) – List of adsorbate-slab results.

  • adslab_anomalies_list (list[list[str]]) – List of detected anomalies for each adsorbate-slab configuration.

Returns:

Sorted list of adsorbate-slab configurations without anomalies.

Return type:

list[dict]

core.components.calculate.recipes.adsorbml.detect_anomaly(initial_atoms: ase.atoms.Atoms, final_atoms: ase.atoms.Atoms, final_slab_atoms: ase.atoms.Atoms) → list[Literal['adsorbate_dissociated', 'adsorbate_desorbed', 'surface_changed', 'adsorbate_intercalated']]#

Detect anomalies between initial and final atomic structures.

Parameters:

  • initial_atoms (Atoms) – Initial atomic structure.

  • final_atoms (Atoms) – Final atomic structure.

Returns:

List of detected anomalies.

Return type:

list[Literal[“adsorbate_dissociated”, “adsorbate_desorbed”, “surface_changed”, “adsorbate_intercalated”]]

core.components.calculate.recipes.adsorbml.run_adsorbml(slab, adsorbate, calculator, optimizer_cls: ase.optimize.Optimizer, fmax: float = 0.02, steps: int = 300, num_placements: int = 100, reference_ml_energies: bool = True, relaxed_slab_atoms: ase.atoms.Atoms = None, place_on_relaxed_slab: bool = False)#

Run the AdsorbML pipeline for a given slab and adsorbate using a pretrained ML model. :param slab: The clean slab structure to which the adsorbate will be added. :type slab: ase.Atoms :param adsorbate: A string identifier for the adsorbate from the database (e.g., ‘*O’). :type adsorbate: str :param reference_ml_energies: If True, assumes the model is a total energy model and references energies

to gas phase and bare slab, by default True since the default model is a total energy model.

Parameters:

  • num_placements (int, optional) – Number of initial adsorbate placements to generate for relaxation, by default 100.

  • fmax (float, default 0.02.) – Relaxation force convergence threshold

  • steps (int, default 300) – Max number of relaxation steps

  • relaxed_slab_atoms (ase.Atoms, optional) – DFT Relaxed slab atoms for anomaly detection for adsorption energy models, by default None.

  • place_on_relaxed_slab (bool, optional) – Whether to place adsorbates on the relaxed slab or initial unrelaxed slab, by default False.

Returns:

Dictionary containing the ML-relaxed slab, adsorbate-slab configurations, energies, and validation results (matching the AdsorbMLSchema format).

Return type:

dict

Contents