ccu.adsorption.sites

Find and distinguish adsorption sites.

This module defines the AdsorptionSite named tuple which represents an adsorption site as a point in space characterized by a surface norm, description, and a set of alignments (represented by the SiteAlignment class). In addition, this module defines the SiteFinder protocol and the HubSpokeFinder and Triangulator classes whose instances implement this protocol.

Example

>>> from ase.build import fcc100
>>> from ccu.adsorption.sites import HubSpokeFinder, HUB_TAG, SPOKE_TAG
... # Construct a surface
>>> cu100 = fcc100("Cu", (3, 3, 1))
... # Tag the hub-and-spoke atoms appropriately
>>> tags = [0] * len(cu100)
>>> tags[1] = tags[3] = SPOKE_TAG
>>> tags[4] = HUB_TAG
>>> cu100.set_tags(tags)
>>> finder = HubSpokeFinder()
>>> sites = finder(cu100)
... # This first site is on the first spoke
>>> (sites[0].position == cu100[1].position).all()
True
class ccu.adsorption.sites.AdsorptionSite(position: NDArray[np.floating], description: str, alignments: list[SiteAlignment], norm: NDArray[np.floating])[source]

Bases: NamedTuple

An adsorption site.

Variables:

  • position (NDArray[np.floating]) – A length 3, 1D numpy.ndarray representing the location of the adsorption site.

  • description (str) – A description of the adsorption site as a string.

  • alignments (list[ccu.adsorption.sites.SiteAlignment]) – A list of SiteAlignment objects defining alignments for the site.

  • norm (NDArray[np.floating]) – A length 3, 1D numpy.ndarray representing the unit normal vector for the surface hosting the adsorption site.

Create new instance of AdsorptionSite(position, description, alignments, norm)

_asdict()

Return a new dict which maps field names to their values.

_field_defaults = {}
_fields = ('position', 'description', 'alignments', 'norm')
classmethod _make(iterable)

Make a new AdsorptionSite object from a sequence or iterable

_replace(**kwds)

Return a new AdsorptionSite object replacing specified fields with new values

alignments: list[SiteAlignment]

Alias for field number 2

description: str

Alias for field number 1

norm: NDArray[np.floating]

Alias for field number 3

position: NDArray[np.floating]

Alias for field number 0

ccu.adsorption.sites.HUB_TAG = -2

The default tag used to identify the hub atom in HubSpokeFinders

class ccu.adsorption.sites.HubSpokeFinder(ignore_identical_spokes: bool = True, norm_convention: Literal['up', 'down'] = 'up', spoke_tag: int = -1, hub_tag: int = -2)[source]

Bases: SiteFinder

A SiteFinder that finds sites in a hub-and-spoke fashion.

The hub-and-spoke model describes a set of adsorption sites on a structure. The “hub” is comprised of one atom, and the “spokes” are imaginary lines drawn from the hub to other atoms in the structure.

Variables:

  • ignore_identical_spokes – Whether or not to restrict the returned sites to ignore those “spoke” sites on atoms of the same chemical symbol.

  • norm_convention – The convention with which to define normal vectors as outwards or inwards from the surface. The choices of "up" and "down" correspond to setting reverse=False and reverse=True in calculate_norm().

  • spoke_tag – The tag designating spoke atoms.

  • hub_tag – The tag designating hub atoms.

See also

calculate_norm()

Construct a HubSpokeFinder.

Parameters:

  • ignore_identical_spokes – Whether or not to restrict the returned sites to ignore those “spoke” sites on atoms of the same chemical symbol.

  • norm_convention – The convention with which to define normal vectors as outwards or inwards from the surface. The choices of "up" and "down" correspond to setting reverse=False and reverse=True in calculate_norm().

  • spoke_tag – The tag designating spoke atoms. Defaults to SPOKE_TAG.

  • hub_tag – The tag designating hub atoms. Defaults to HUB_TAG.

_abc_impl = <_abc._abc_data object>
_is_protocol = False
ccu.adsorption.sites.SITE_TAG = -1

The default tag used to identify site atoms in Triangulators

ccu.adsorption.sites.SPOKE_TAG = -1

The default tag used to identify spoke atoms in HubSpokeFinders

class ccu.adsorption.sites.SiteAlignment(direction: NDArray[np.floating], description: str)[source]

Bases: NamedTuple

An alignment that an adsorbate can assume on a site.

Variables:

  • direction (NDArray[np.floating]) – A length 3, 1D numpy.ndarray of floats representing a direction in space.

  • description (str) – A description of the site alignment.

Create new instance of SiteAlignment(direction, description)

_asdict()

Return a new dict which maps field names to their values.

_field_defaults = {}
_fields = ('direction', 'description')
classmethod _make(iterable)

Make a new SiteAlignment object from a sequence or iterable

_replace(**kwds)

Return a new SiteAlignment object replacing specified fields with new values

description: str

Alias for field number 1

direction: NDArray[np.floating]

Alias for field number 0

class ccu.adsorption.sites.SiteFinder(*args, **kwargs)[source]

Bases: Protocol

A protocol for finding adsorption sites.

_abc_impl = <_abc._abc_data object>
_is_protocol = True
class ccu.adsorption.sites.Triangulator(ignore_identical_sites: bool = True, norm_convention: Literal['up', 'down'] = 'up', site_tag: int = -1)[source]

Bases: SiteFinder

A SiteFinder that triangulates sites.

A Triangulator finds sites at the vertices, midpoints, and centroid of a triangle.

Variables:

  • ignore_identical_sites – Whether or not to restrict the returned sites to ignore those sites on atoms of the same chemical symbol.

  • norm_convention – The convention with which to define normal vectors as outwards or inwards from the surface. The choices of "up" and "down" correspond to setting reverse=False and reverse=True in calculate_norm().

  • site_tag – The tag designating site atoms.

See also

calculate_norm()

Construct a HubSpokeFinder.

Parameters:

  • ignore_identical_sites – Whether or not to restrict the returned sites to ignore those sites on atoms of the same chemical symbol.

  • norm_convention – The convention with which to define normal vectors as outwards or inwards from the surface. The choices of "up" and "down" correspond to setting reverse=False and reverse=True in calculate_norm().

  • site_tag – The tag designating site atoms. Defaults to SITE_TAG.

_abc_impl = <_abc._abc_data object>
_is_protocol = False