shnitsel.geo.alignment#

Functions#

get_centered_geometry(atXYZ[, by_mass])

Helper function to set the center of the geometry (i.e. mean along the atom axis) to zero.

rotational_procrustes_np(A, B[, weight])

Rotationally align the geometrie(s) in A to the single geometry in B.

rotational_procrustes(A, B[, dim0, dim1, weight])

Rotationally align the geometry or geometries in A to the single geometry in B.

kabsch(atXYZ[, reference_or_indexers])

Rotationally align the molecular geometries in atXYZ to a single molecular geometry.

Module Contents#

get_centered_geometry(atXYZ, by_mass=False)#

Helper function to set the center of the geometry (i.e. mean along the atom axis) to zero.

Parameters:

  • atXYZ (AtXYZ) – Array of positional data

  • by_mass (Literal[False], optional) – Flag whether the centering/average should be center of mass or just plain average of positions. Defaults to False.

Raises:

NotImplementedError – Centering the COM instead of the mean is currently not implemented.

Returns:

Resulting positions after centering.

Return type:

AtXYZ

rotational_procrustes_np(A, B, weight=None)#

Rotationally align the geometrie(s) in A to the single geometry in B.

This helper function is specifically tailored to work directly on numpy arrays in contrast to its namesake rotational_procrustes(), which accepts xarray.DataArray parameters.

Parameters:

  • A (np.ndarray) – The geometries to process with shape (n_geometries, n_points, n_coordinates)

  • B (np.ndarray) – The reference geometry with shape (n_points, n_coordinates)

  • weight (Sequence[float], optional) – How much importance should be given to the alignment of each point, by default equal importance

Returns:

An array with the same shape as A

Return type:

np.ndarray

Notes

We are solving the following minimization problem for each geometry A(i): .. math:

\min_R \Vert A(i)R - B\Vert^2_F

For this, we calculte the weighted cross-covariance matrix: We are solving the minimization problem .. math:

C = A^T B

And then we find the SVD .. math:

C = U \Sigma V^T

Which provides us with the optimum rotation: .. math:

R = V U^T

If the resulting R has negative determinant, the rotation is instead a mirroring operation and we invert the sign of the last column of vt to restore rotational properties.

rotational_procrustes(A, B, dim0='atom', dim1='direction', weight=None)#

Rotationally align the geometry or geometries in A to the single geometry in B.

Parameters:

  • A (xr.DataArray) – The (optionally multiple) geometries to process

  • B (xr.DataArray) – The reference geometry

  • dim0 (str, optional) – The name of the dimension over points to be rotated; must be present in A and ``B`; by default ‘atom’

  • dim1 (str, optional) – The name of the dimension over the coordinates of the aforementioned points; must be present in A and ``B`; by default ‘direction’

  • weight (Sequence[float], optional) – How much importance should be given to the alignment of each point (atom), by default equal importance

Returns:

An xr.DataArray with the same shape as A but with entries aligned to the overall geometry of B

Return type:

xr.DataArray

kabsch(atXYZ, reference_or_indexers=None, **indexers_kwargs)#

Rotationally align the molecular geometries in atXYZ to a single molecular geometry.

If no reference_or_indexers argument (or the indexers_kwargs option) is passed, this function will try to use the first frame or first timestep in atXYZ as a reference.

Parameters:

  • atXYZ (xr.DataArray) – The geometries to process (with dims ‘atom’, ‘direction’)

  • reference_or_indexers (xr.DataArray | dict, optional) – Either a reference geometry (with dims ‘atom’, ‘direction’) or an indexer dictionary which will be passed to atXYZ.sel() to indetify a single geometry in the atXYZ parameter to use as a reference point.

  • **indexer_kwargs – The keyword-argument form of the indexer to be passed to atXYZ.sel()

Returns:

The aligned geometries

Return type:

xr.DataArray

Raises:

ValueError – If nothing is done to indicate a reference geometry, i.e. neither reference_or_indexers nor indexer_kwargs are passed