ccu.adsorption package¶

Utilities for adsorption studies.

Example

Generate adsorbate complexes for all CO₂RR intermediates on Au

>>> from ase.build import bulk
>>> import numpy as np
>>>
>>> from ccu.adsorption.adsorbatecomplex import AdsorbateComplexFactory
>>> from ccu.adsorption.adsorbates import CO2RR_ADSORBATES
>>> from ccu.adsorption.sitefinder import AdsorptionSite
>>> from ccu.adsorption.sitefinder import SiteAlignment
>>>
>>> catalyst = bulk("Au") * 3
>>> catalyst.center(vacuum=10, axis=2)
>>> norm_vector = np.array([0, 0, 1])
>>> surface_atom = max(catalyst, key=lambda atom: atom.position[2])
>>> alignment = SiteAlignment(norm_vector, "vertical")
>>> site = AdsorptionSite(
...     location=surface_atom.position,
...     description="on-top",
...     alignments=[alignment],
...     surface_norm=norm_vector,
... )
>>> for adsorbate in CO2RR_ADSORBATES:
...     factory = AdsorbateComplexFactory(adsorbate, catalyst)
...     for complex in factory(site):
...

Submodules¶

ccu.adsorption.adsorbatecomplex module¶

Classes for producing catalyst-adsorbate complexes.

Specifically, this module provides the AdsorbateComplex and AdsorbateComplexFactory classes.

class ccu.adsorption.adsorbatecomplex.AdsorbateComplex(adsorbate_description: str, site_description: str, orientation_description: str, structure_description: str, structure: Atoms)[source]¶

Bases: object

An adsorbate complex.

Variables:

adsorbate_description – A description of the adsorbate.
structure_description – A description of the surface structure.
site_description – A description of the adsorption site.
orientation_description – A description of the adsorbate orientation.
structure – The atoms.Atoms object representing the adsorbate complex.

Initialize an instance from its attributes.

Parameters:

adsorbate_description – A description of the adsorbate.
site_description – A description of the adsorption site.
orientation_description – A description of the adsorbate orientation.
structure_description – A description of the surface structure.
structure – The atoms.Atoms object representing the adsorbate complex.

write(destination: Path | None = None) → Path[source]¶

Write the AdsorbateComplex object to an ASE .traj file.

Parameters:: destination – A Path indicating the directory in which to write the .traj file. Defaults to the current working directory.
Returns:: A Path indicating the filename of the written .traj file.

class ccu.adsorption.adsorbatecomplex.AdsorbateComplexFactory(adsorbate: Atoms, structure: Atoms, separation: float = 1.8, special_centres: bool = False, symmetric: bool = False, vertical: bool = False)[source]¶

Bases: object

An AdsorbateComplex factory.

Given an adsorbate, a structure, and various configuration specifications (e.g., symmetric, vertical), an AdsorbateComplexFactory determines all of the adsorption sites and corresponding adsorbate configurations.

Variables:

_structure – An atoms.Atoms instance representing the surface structure.
separation – The distance (in Angstroms) that the adsorbate should be placed from the surface. Defaults to 1.8.
special_centres – A bool indicating whether atom-centred placement will be used in addition to centre-of-mass placement.
symmetric – A bool indicating whether or not the adsorbate is to be treated as symmetric.
vertical – A bool indicating whether or not to consider vertical adsorption sites.

Create an AdsorbateComplexFactor.

Parameters:

adsorbate – The adsorbate in the complex.
structure – The structure on which to place the adsorbate.
separation – The distance (in Angstroms) that the adsorbate should be placed from the surface. Defaults to 1.8.
special_centres – Whether or not to produce atom-centred placements. Defaults to False.
symmetric – Whether or not to treat the adsorbate as symmetric. Defaults to False.
vertical – Whether to produce vertical orientations. Defaults to False.

Note

In addition to setting special centres to True, one must also specify the indices of the atomic centres in order to use atom-centred placement. Specifically, the "special_centres" key in adsorbates‘s atoms.Atoms.info dictionary must map to an iterable whose elements specify the indices of the atoms to be used to centre the adsorbate. If this key is not present in the info attribute, then the position of the atom in adsorbate with index 0 will be used to centre the adsorbate.

property adsorbate: Atoms¶: The adsorbate to be placed.

adsorbate_orientations(site: AdsorptionSite) → list[AdsorbateOrientation][source]¶

Generate all adsorbate orientations for a given adsorption site.

Parameters:: site – An ccu.adsorption.sitefinder.AdsorptionSite for which to generate adsorbate orientations.
Returns:: A list of adsorbateorientation.AdsorbateOrientation instances.

next_complex(site: AdsorptionSite, adsorbate_tag: int = -99) → Iterator[AdsorbateComplex][source]¶

Yield next adsorbate-surface complex for a given site.

Parameters:

site – A sitefinder.AdsorptionSite instance which represents the site for which to generate complexes.
adsorbate_tag – An integer with which to tag the adsorbate to enable tracking. Defaults to -99.

orient_adsorbate(orientation: AdsorbateOrientation) → Atoms[source]¶

Orients the AdsorbateComplexFactory’s adsorbate.

Parameters:: orientation – An adsorbateorientation.AdsorbateOrientation instance representing the orientation in which the adsorbate is to be directed.
Returns:: An atoms.Atoms instance representing the oriented adsorbate as a copy of the AdsorbateComplexFactory’s adsorbate.

Note

The adsorbate is oriented such that its primary axis is aligned with the primary orientation vector of the given adsorbateorientation.AdsorbateOrientation object and its secondary axis is in the plane defined by the primary axis of the adsorbate and the secondary orientation.

place_adsorbate(adsorbate: Atoms, site: AdsorptionSite, centre: array = None)[source]¶

Place adsorbate on site.

The adsorbate is placed on the specified site while respecting the minimum specified separation.

Parameters:

adsorbate – An atoms.Atoms instance representing the adsorbate to be moved.
site – A sitefinder.AdsorptionSite instance representing the site on which the adsorbate is to be placed.
centre – A numpy.array designating the centre with which to align the adsorbate. Defaults to None.

property structure: Atoms¶: The structure on which to place the adsorbate.

ccu.adsorption.adsorbatecomplex.generate_complexes(adsorbate: str, structure: Path, destination: Path | None = None, separation: float = 1.8, special_centres: bool = False, symmetric: bool = False, vertical: bool = False, *, finder: str = 'MOF') → list[tuple[AdsorbateComplex, Path]][source]¶

Create adsorbate complexes and write them to a .traj file.

Parameters:

adsorbate – A string indicating the name of the adsorbate to place on the surface.
structure – A Path indicating the filename of the structure on which the adsorbate will be placed.
destination – A Path indicating the directory in which to write the .traj files. The directory is created if it does not exist. Defaults to the current working directory.
separation – A float indicating how far (in Angstroms) the adsorbate should be placed from the surface. Defaults to 1.8.
special_centres – A bool indicating whether atom-centred placement will be used in addition to centre-of-mass placement.
symmetric – A bool indicating whether or not the adsorbate is to be treated as symmetric. Defaults to False.
vertical – A bool indicating whether or not vertical adsorption configurations are to be generated. Defaults to False.
finder – The type of ccu.adsorption.sitefinder.SiteFinder. Defaults to "MOF".

Returns:

A list of 2-tuples (complex_i, path_i) where complex_i is the ith AdsorbateComplex and path_i is a Path representing the filename under which complex_i was saved.

ccu.adsorption.adsorbateorientation module¶

Classes for orienting adsorbates on adsorption sites.

class ccu.adsorption.adsorbateorientation.AdsorbateOrientation(description: str, orientation_vectors: Sequence[array])[source]¶

Bases: object

An orientation of an adsorbate.

An AdsorbateOrientation object contains the information required to unambiguously orient an adsorbate in space.

Variables:

description – A string describing the adsorbate orientation.
vectors – A tuple of numpy.array instances which are the vectors along which an adsorbate will be oriented. The sequence should contain two linearly independent unit vectors. The first vector is the primary orientation axis. The secondary vector is secondary orientation axis.

Create an adsorbate orientation.

Parameters:

description – A description of the orientation.
orientation_vectors – Two linearly independent vectors with which to orient the adsorbate.

class ccu.adsorption.adsorbateorientation.AdsorbateOrientationFactory(site: AdsorptionSite, adsorbate: Atoms, force_symmetry: bool = False, vertical: bool = False)[source]¶

Bases: object

An AdsorbateOrientation factory.

An AdsorbateOrientationFactory creates a collection of AdsorbateOrientation objects for a given AdsorptionSite subject to symmetry and orientation specifications.

Variables:

site – A sitefinder.AdsorptionSite instance indicating site for which the orientations are to be created.
adsorbate – An ase.Atoms instance representing the adsorbate which will assume the orientations.
force_symmetry – A boolean indicating whether or not to force the adsorbate to be treated as symmetric.
vertical – A boolean indicating whether or not vertical orientations will be created.

Create a factory.

Parameters:

site – The site on which the adsorbate will reside.
adsorbate – The adsorbate to orient.
force_symmetry – Whether or not to treat the adsorbate as symmetric. Defaults to False.
vertical – Whether or not to generate vertical orientations. Defaults to False.

create_orientations() → list[AdsorbateOrientation][source]¶

Creates a list of AdsorbateOrientation objects.

Returns:: A list of AdsorbateOrientation objects.

ccu.adsorption.adsorbates module¶

Reaction intermediates for CO₂RR, NRR/UOR, OER/ORR, and HER.

CO₂RR Intermediates from Nitopi et al. [1]

NRR/UOR Intermediates Wan et al. [2] and Li et al. [3]

Bond lengths, angles and positions from NIST.

Example

>>> from ccu.adsorption.adsorbates import get_adsorbate
>>> get_adsorbate("CO2")
Atoms(symbols='CO2', pbc=False)

ccu.adsorption.adsorbates.get_adsorbate(adsorbate: str) → Atoms[source]¶

Return the requested adsorbate as an ase.Atoms object.

Parameters:: adsorbate – The name of the adsorbate to retrieve as a string (case-insensitive).
Raises:: NotImplementedError – The requested adsorbate is neither a molecule supported by ASE nor a defined adsorbate in ccu.adsorption.adsorbates.
Returns:: An atoms.Atoms instance representing the requested adsorbate.

ccu.adsorption.cli module¶

CLI utilities for adsorption studies.

ccu.adsorption.cli.print_adsorbates(ctx: Context, value: Any, param: Parameter) → None[source]¶: Print a list of all adsorbates available to ccu.

ccu.adsorption.sitefinder module¶

Classes for locating and distinguishing adsorption sites.

Specifically, this module provides the AdsorptionSite, SiteFinder, and MOFSiteFinder classes.

class ccu.adsorption.sitefinder.AdsorptionSite(location: Sequence[float], description: str, alignments: Iterable[SiteAlignment], surface_norm: Sequence[float])[source]¶

Bases: object

An adsorption site.

Variables:

location – A numpy.array representing the location of the adsorption site.
description – A description of the adsorption site as a string.
alignments – A list of SiteAlignment objects defining alignments for the site.
surface_norm – A numpy.array representing the unit normal vector for the surface hosting the adsorption site.

Initialize an adsorption site.

Parameters:

location – A 3-element sequence of floats identify the adsorption site in space.
description – A description of the adsorption site.
alignments – A list of alignments characterizing the site.
surface_norm – A 3-element sequence representing the direction of the site surface norm.

class ccu.adsorption.sitefinder.MOFSite(location: Sequence[float], description: str, alignment_atoms: Iterable[Atom], site_anchor: Sequence[float], surface_norm: Sequence[float], intermediate_alignments: bool = False)[source]¶

Bases: AdsorptionSite

An adsorption site within a MOF.

Variables:

location – A numpy.array representing the location of the adsorption site.
description – A description of the adsorption site as a string.
alignments – A list of SiteAlignment objects defining alignments for the site.
surface_norm – A numpy.array representing the normal vector for the surface hosting the adsorption site.
intermediate_alignments – A bool indicating whether or not to consider intermediate alignments.

Create a site on a metal-organic framework.

Parameters:

location – A numpy.array representing the location of the adsorption site.
description – A description of the adsorption site as a string.
alignment_atoms – A list of atom.Atom instances, which, in concert with site_anchor can be used to generate alignment directions.
site_anchor – A 3-element sequence of floats representing a reference location in space to be used to generate alignment directions. The generated alignments will constitute every direction from from the site anchor to an alignment atom.
surface_norm – A numpy.array representing the normal vector for the surface hosting the adsorption site.
intermediate_alignments – A bool indicating whether or not to consider intermediate alignments. Defaults to False.

create_alignments(alignment_atoms: Iterable[Atom], site_anchor: Sequence[float]) → list[SiteAlignment][source]¶

Creates the SiteAlignment objects for a MOFSite.

Parameters:

alignment_atoms – An iterable containing atom.Atom instances which will be used to define alignment directions.
site_anchor – A sequence of 3 floats representing a reference location using for defining alignment directions. This is usually the position of the metal atom in the site.

Returns:

A list of SiteAlignment instances representing the alignments for a MOFSite instance.

create_intermediate_alignments(colinear_vectors: list[Sequence[float]]) → list[SiteAlignment][source]¶

Create intermediate alignments.

Parameters:: colinear_vectors – 3-float sequences representing the direction of the intermediate alignments.
Returns:: A list of SiteAlignment instances representing the intermediate alignments for a MOFSite instance.

class ccu.adsorption.sitefinder.MOFSiteFinder(structure: Atoms, *, between_linkers: bool = False)[source]¶

Bases: SiteFinder

Find adsorption sites on MOF surfaces.

Currently, the atoms bonded to the metal within the SBU must possess tags of 1 and the metal must possess a tag of 2 for the implementation to work correctly.

Variables:

structure – An atoms.Atoms object representing a metal-organic framework.
DEFAULT_SBU_TAG (ClassVar[int]) – The default tag for the secondary building unit central atom

Create a ccu.adsorption.sitefinder.MOFSiteFinder.

Parameters:

structure – The structure on which to find adsorption sites.
between_linkers – Whether to include between linker sites. Defaults to False.

DEFAULT_SBU_TAG: ClassVar[int] = 2¶

property adjacent_linkers: list[Atom]¶: ase.Atom instances representing adjacent linker atoms.

create_between_linker_site() → MOFSite[source]¶: Returns an adsorption site centred between the MOF linker atoms.

create_linker_sites() → list[MOFSite][source]¶: Returns a list of adsorption sites centred on MOF linker atoms.

create_metal_site() → MOFSite[source]¶: Returns an adsorption site centred on the MOF metal atom.

property sbu_metal: Atom¶: The metal atom within the SBU of the MOF.

sites() → list[AdsorptionSite][source]¶

Determines all unique SBU adsorption sites for a given MOF.

Note that the AdsorptionSite instances are defined such that the first and second elements in their “alignment_atoms” attribute are linker atoms and the third element is the metal.

Returns:: A list of AdsorptionSite instances representing the SBU adsorption sites of the given MOF.

property surface_norm: array¶

The unit norm to the secondary building unit.

The unit norm is defined relative to the plane determined by two adjacent linker atoms and the metal within the SBU.

class ccu.adsorption.sitefinder.SiteAlignment(alignment_vector: Sequence[float], description: str)[source]¶

Bases: object

An alignment that an adsorbate can assume on a site.

Variables:

vector – A numpy.array representing the alignment vector as a unit vector.
description – A description of the site alignment.

Create a site alignment.

Parameters:

alignment_vector – A 3-element sequence of floats representing a direction in space.
description – A description of the alignment.

class ccu.adsorption.sitefinder.SiteFinder(structure: Atoms)[source]¶

Bases: ABC

An abstract base class for finding adsorption sites.

Subclasses must define the abstract method “sites” which returns all adsorption sites for a given structure.

Create a site finder.

Parameters:: structure – The structure on which to find sites.

abstract sites() → Iterable[AdsorptionSite][source]¶: Subclasses should override this method.