ccu.adsorption package#

Submodules#

ccu.adsorption.adsorbatecomplex module#

Defines the AdsorbateComplex and AdsorbateComplexFactory classes.

class ccu.adsorption.adsorbatecomplex.AdsorbateComplex(site_description: str, orientation_description: str, structure_desription: str, structure: Atoms)[source]#

Bases: object

An adsorbate-surface complex.

Variables:

  • structure_description – A string describing the surface structure.

  • site_description – A string describing the adsorption site.

  • orientation_description – A string describing the orientation of the adsorbate.

  • structure – An ase.Atoms object of the adsorbate-surface complex.

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

Writes the AdsorbateComplex object to an ASE .traj file.

Parameters:

destination – A pathlib.Path instance indicating the directory in which to write the .traj file. Defaults to the current working directory.

Returns:

A pathlib.Path instance indicating the path 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:

  • _adsorbate – An ase.Atoms instance representing the adsorbate.

  • _structure – An ase.Atoms instance representing the surface structure.

  • separation – How far (in Angstroms) the adsorbate should be placed from the surface.

  • special_centres –

    A boolean indicating whether or not atom-centred placement will be used.

    Note that in addition to be set to true, the ase.Atoms instance passed as the adsorbate argument must have the key ‘special centres’ in its info attribute. Further, this key 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 atom with index 0 will be used to centre the adsorbate.

  • symmetric – A boolean indicating whether or not the adsorbate is to be treated as symmetric.

  • vertical – A boolean indicating whether or not to consider vertical adsorption sites.

property adsorbate: Atoms#
adsorbate_orientations(site: AdsorptionSite) → list[ccu.adsorption.adsorbateorientation.AdsorbateOrientation][source]#

Returns a list of all adsorbate orientations for a given adsorption site.

Parameters:

site – A sitefinder.AdsorptionSite instance representing the site for which to generate adsorbate orientations.

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

Yields next adsorbate-surface complex for a given site as an AdsorbateComplex.

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 such that its primary axis is aligned with the primary orientation vector of the given AdsorbateOrientation object and its secondary axis is in the plane defined by the primary axis of the adsorbate and the secondary orientation.

Parameters:

orientation – An adsorbateorientation.AdsorbateOrientation instance representing the orientation in which the adsorbate is to be directed.

Returns:

An ase.Atoms instance representing the oriented adsorbate as a copy of the AdsorbateComplexFactory’s adsorbate.

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

Moves adsorbate to specified site respecting the minimum specified separation.

Parameters:

  • new_adsorbate – An ase.Atoms instance representing theadsorbate to be moved.

  • centre – A numpy.array designating the centre with which to align the adsorbate.

  • site – A sitefinder.AdsorptionSite instance representing the site on which the adsorbate is to be placed.

property structure: Atoms#
ccu.adsorption.adsorbatecomplex.run(adsorbate: str, structure: Path, destination: Path = None, separation: float = 1.8, special_centres: bool = False, symmetric: bool = False, vertical: bool = False)[source]#

Creates MOF-adsorbate complexes for adsorption configurations on the SBU of the given MOF and write them to a .traj file.

Parameters:

  • adsorbate – A string indicating the name of the adsorbate to place on the surface.

  • structure – A pathlib.Path instance indicating the path to the surface on which the adsorbate will be placed.

  • destination – A pathlib.Path instance 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.

  • symmetric – A boolean indicating whether or not the adsorbate is to be treated as symmetric. Defaults to False.

  • vertical – A boolean indicating whether or not vertical adsorption configurations are to be generated. Defaults to False.

ccu.adsorption.adsorbateorientation module#

This module defines the AdsorbateOrientation and AdsorbateOrientationFactory classes.

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.

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_orientations() → list[ccu.adsorption.adsorbateorientation.AdsorbateOrientation][source]#

Creates a list of AdsorbateOrientation objects.

Returns:

A list of AdsorbateOrientation objects.

ccu.adsorption.adsorbates module#

This module defines CO2RR, NRR/UOR, OER/ORR, and HER intermediates.

CO2RR Intermediates from Chem. Rev. 2019, 119, 12, 7610-7672.

NRR/UOR Intermediates from ACS Catal. 2023, 13, 3, 1926-1933. and Angew. Chem. Int. Ed. 2021, 60, 51, 26656.

Bond lengths, angles and positions from cccbdb.nist.gov.

Usage:

>>> from ccu.adsorption.adsorbates import get_adsorbate
>>> get_adsorbate('CO2')
Atoms(symbols='CO2', pbc=False)
ccu.adsorption.adsorbates.get_adsorbate(adsorbate: str) → Atoms[source]#

Returns 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 ase.Atoms instance representing the requested adsorbate.

ccu.adsorption.cli module#

This module contains the ccu.structure package CLI logic.

ccu.adsorption.sitefinder module#

Defines 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 for an adsorbate.

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

  • site. (the surface hosting the adsorption) –

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 boolean indicating whether or not to consider intermediate alignments.

create_alignments(alignment_atoms: Iterable[Atom], site_anchor: Sequence[float]) → list[ccu.adsorption.sitefinder.SiteAlignment][source]#

Creates the SiteAlignment objects for a MOFSite.

Parameters:

  • alignment_atoms – An iterable containing ase.Atom instances which will be used to define alignment directions.

  • site_anchor – A sequence of 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: Iterable[SiteAlignment]) → list[ccu.adsorption.sitefinder.SiteAlignment][source]#
class ccu.adsorption.sitefinder.MOFSiteFinder(structure: Atoms)[source]#

Bases: SiteFinder

A SiteFinder subclass which finds 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.

Parameters:

structure – An ase.Atoms object representing a metal-organic framework.

property adjacent_linkers: list[ase.atom.Atom]#

A list of ase.Atom instances representing two adjacent linker atoms.

create_between_linker_site() → MOFSite[source]#

Returns a MOFSite instance representing an adsorption site centred between the MOF linker atoms.

create_linker_sites() → list[ccu.adsorption.sitefinder.MOFSite][source]#

Returns a list of MOFSite instances representing adsorption sites centred on the MOF linker atoms.

create_metal_site() → MOFSite[source]#

Returns a MOFSite instance representing an adsorption site centred on the MOF metal atom.

property sbu_metal: Atom#

An ase.Atom instance representing the metal atom within the SBU of the MOF.

sites() → list[ccu.adsorption.sitefinder.AdsorptionSite][source]#

Determines all unique SBU adsorption sites for a given MOF.

Note that the AdsorptionSites 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#

A unit vector normal 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 string describing the site alignment.

class ccu.adsorption.sitefinder.SiteFinder[source]#

Bases: ABC

An abstract base class for objects which find adsorption sites for particular surfaces.

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

abstract sites() → Iterable[AdsorptionSite][source]#

Subclasses should override this method.

Module contents#