ccu.structure.geometry

Geometry-related functions for atomic structures.

class ccu.structure.geometry.MolecularOrientation(directions: tuple[NDArray[np.floating], NDArray[np.floating]], description: str)

Bases: NamedTuple

The orientation of a molecule.

A MolecularOrientation tuple contains the information required to unambiguously orient a molecule in space, for example, on an AdsorptionSite.

Variables:

• directions (tuple[numpy.ndarray[Any, numpy.dtype[numpy.floating]], numpy.ndarray[Any, numpy.dtype[numpy.floating]]]) – A 2-tuple of length 3, 1D, numpy.ndarrays representing the primary and secondary orientation directions. These directions orient an adsorbate in site space.

• description (str) – A string describing the adsorbate orientation.

Create new instance of MolecularOrientation(directions, description)

_asdict()

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

_field_defaults = {}

_fields = ('directions', 'description')

classmethod _make(iterable)

Make a new MolecularOrientation object from a sequence or iterable

_replace(**kwds)

Return a new MolecularOrientation object replacing specified fields with new values

description: str

Alias for field number 1

directions: tuple[ndarray[Any, dtype[floating]], ndarray[Any, dtype[floating]]]

Alias for field number 0

ccu.structure.geometry.align(adsorbate: Atoms, directions: Sequence[Iterable[float]], center: Iterable[float] | None = None) → Atoms

Align a molecule according to its primary and secondary axes.

Parameters:

• adsorbate – An Atoms representing a molecule.

• directions – A sequence whose first and second elements are length 3, iterables of floats representing the primary and secondary directions along which adsorbate is to be aligned.

• center – A point to remain fixed while aligning adsorbate. Defaults to the center-of-mass of adsorbate.

Returns:

A copy of adsorbate aligned such that its primary and secondary axes coincide with directions[0] and directions[1], respectively.

ccu.structure.geometry.calculate_norm(points: list[ndarray[Any, dtype[floating]]], *, reverse: bool = False) → ndarray[Any, dtype[floating]]

Calculate the norm for the average plane defined by a set of points.

Parameters:

• points – A list of points on a surface. These points should be approximately coplanar.

• reverse – Whether or not to reverse the preferred direction for the norm. Defaults to False in which case the norm direction is determined as follows. If the vector does not lie in the xy-plane, then the norm is normalized to have positive z. Otherwise, if the vector has a y component, then it is normalized to have positive y. and if it has no y component, then it is normalized to have positive x. If True, then the norm is normalized to have negative z in the above cases.

Returns:

A length 3, 1D numpy.ndarray representing the unit normal vector for the average plane defined by points.

Raises:

ValueError – Less than three non-colinear points provided.

ccu.structure.geometry.calculate_separation(structure1: Atoms, structure2: Atoms) → float

Calculates the separation between two Atoms instances.

The distance is defined as the smallest distance between an atom in one structure and an atom in the second structure.

Parameters:

• structure1 – An Atoms instance.

• structure2 – An Atoms instance.

Returns:

A float representing the separation between the two structures.