molgri.space.utils

Useful functions for rotations and vectors.

Functions that belong in this module perform simple conversions, normalisations or assertions that are useful at various points in the molgri.space subpackage.

Functions

angle_between_vectors(central_vec, side_vector)	Having two vectors or two arrays in which each row is a vector, calculate all angles between vectors.
cart2sph(x, y, z)	Transform an individual 3D point from cartesian to spherical coordinates.
cart2sphA(pts)	Transform an array of shape (N, 3) in cartesian coordinates to an array of the same shape in spherical coordinates.
dist_on_sphere(vector1, vector2)	Args:
norm_per_axis(array[, axis])	Returns the norm of the vector or along some axis of an array.
normalise_vectors(array[, axis, length])	Returns the unit vector of the vector or along some axis of an array.
random_quaternions([n])	Create n random quaternions
random_sphere_points([n])	Create n points that are truly randomly distributed across the sphere.
randomise_quaternion_set_signs(quaternions)	Return the set of the same quaternions up to the sign of each row, which is normalised.
standardise_quaternion_set(quaternions[, ...])	Since quaternions double-cover rotations, standardise all quaternions in this array so that their dot product with the "standard" quaternion is positive.
unique_quaternion_set(quaternions)	Standardise the quaternion set so that q and -q are converted to the same object.

molgri.space.utils.norm_per_axis(array: ndarray, axis: int | None = None) → ndarray

Returns the norm of the vector or along some axis of an array. Default behaviour: if axis not specified, normalise a 1D vector or normalise 2D array row-wise. If axis specified, axis=0 normalises column-wise and axis=1 row-wise.

Args:

array: numpy array containing a vector or a set of vectors that should be normalised - per default assuming

every row in an array is a vector

axis: optionally specify along which axis the normalisation should occur

Returns:

an array of the same shape as the input array where each value is the norm of the corresponding vector/row/column

molgri.space.utils.normalise_vectors(array: ndarray, axis: int | None = None, length=1) → ndarray

Returns the unit vector of the vector or along some axis of an array. Default behaviour: if axis not specified, normalise a 1D vector or normalise 2D array row-wise. If axis specified, axis=0 normalises column-wise and axis=1 row-wise.

Args:

array: numpy array containing a vector or a set of vectors that should be normalised - per default assuming

every row in an array is a vector

axis: optionally specify along which axis the normalisation should occur length: desired new length for all vectors in the array

Returns:

an array of the same shape as the input array where vectors are normalised, now all have length ‘length’

molgri.space.utils.angle_between_vectors(central_vec: ndarray, side_vector: ndarray) → array

Having two vectors or two arrays in which each row is a vector, calculate all angles between vectors. For arrays, returns an array giving results like those:

……………………………. | …………………………… | ….. |

---

Angle between vectors equals the distance between two points measured on a surface of an unit sphere!

Args:

central_vec: first vector or array of vectors side_vector: second vector or array of vectors

Returns:

molgri.space.utils.dist_on_sphere(vector1: ndarray, vector2: ndarray) → ndarray

Args:

vector1: vector shape (n1, d) or (d,) vector2: vector shape (n2, d) or (d,)

Returns:

an array the shape (n1, n2) containing distances between both sets of points on sphere

molgri.space.utils.cart2sph(x: float, y: float, z: float) → Tuple[float, float, float]

Transform an individual 3D point from cartesian to spherical coordinates.

Code obtained from Leon Wehrhan.

molgri.space.utils.cart2sphA(pts: ndarray[Any, dtype[ScalarType]]) → ndarray[Any, dtype[ScalarType]]

Transform an array of shape (N, 3) in cartesian coordinates to an array of the same shape in spherical coordinates. Can be used to create a hammer projection plot. In this case, disregard column 0 of the output and plot columns 1 and 2.

Code obtained from Leon Wehrhan.

molgri.space.utils.standardise_quaternion_set(quaternions: ndarray[Any, dtype[ScalarType]], standard=array([1, 0, 0, 0])) → ndarray[Any, dtype[ScalarType]]

Since quaternions double-cover rotations, standardise all quaternions in this array so that their dot product with the “standard” quaternion is positive. Return the quaternion array where some elements ma have been flipped to -q.

Idea: method 2 described here: https://math.stackexchange.com/questions/3888504/component-wise-averaging-of-similar-quaternions-while-handling-quaternion-doubl

Args:

quaternions: array (N, 4), each row a quaternion standard: a single quaternion determining which half-hypersphere to use

molgri.space.utils.unique_quaternion_set(quaternions: ndarray[Any, dtype[ScalarType]]) → ndarray[Any, dtype[ScalarType]]

Standardise the quaternion set so that q and -q are converted to the same object. If now any repetitions exist, remove them from the array.

Args:

quaternions: array (N, 4), each row a quaternion

Returns:

quaternions: array (M <= N, 4), each row a quaternion different from all other ones

molgri.space.utils.randomise_quaternion_set_signs(quaternions: ndarray[Any, dtype[ScalarType]]) → ndarray[Any, dtype[ScalarType]]

Return the set of the same quaternions up to the sign of each row, which is normalised.

molgri.space.utils.random_sphere_points(n: int = 1000) → ndarray[Any, dtype[ScalarType]]

Create n points that are truly randomly distributed across the sphere.

Args:

n: number of points

Returns:

an array of grid points, shape (n, 3)

molgri.space.utils.random_quaternions(n: int = 1000) → ndarray[Any, dtype[ScalarType]]

Create n random quaternions

Args:

n: number of points

Returns:

an array of grid points, shape (n, 4)