transform module

Isometric transformations, rotation-translation operators & their derivatives.

Module author: Brynmor K. Chapman.

Module author: Michael S. Chapman <chapmami@ohsu.edu>

Authors:

Michael S. Chapman <chapmami@ohsu.edu>,

Oregon Health & Science University

Version:

0.5, March 23, 2016

Changed in version Start: 01/20/12

Changed in version 0.3.7: 11/1/12 - Incorporate functions from Brynmor’s TAProtein(_copy).py.

Changed in version 0.5.0: 05/16/15 ReStructuredText docs

Bibliography:

• <http://en.wikipedia.org/wiki/Rotation_matrix> - excellent.

• <http://en.wikipedia.org/wiki/Jacobian_matrix_and_determinant> - peripheral.

• Biomolecular Crystallography, Bernard Rupp, Garland (2010):

  • Section 11.1: rotational operators.
  • Appendix A.7: direction cosines in spherical coordinates.

class transform.AugmentedOperator(augmented_operator=None, rotation=None, origin=matrix([[ 0.], [ 0.], [ 0.]]), translation=matrix([[ 0.], [ 0.], [ 0.]]))

Bases: object

Manages 4x4 operator x’ = [O]x, equiv to x’ = [R]x + t, arbitrary origin.

Variables:

• O – operator
• origin – for rotation, implicit in self.O, but needed for Jacobian

Instantiate Operator O, calculated a variety of ways.

Either 4x4 augmented_operator or (rotation + origin + translation) must be provided.

Parameters:

• rotation (array-like[3,3]) – rotation matrix.
• origin (array-like(shape = 3)) – for rotation
• translation (array-like[3]) –

augment(rotation_matrix, origin, translation, verbose=False)

4x4 Operator from rotation matrix / translation + origin.

Parameters:

• rotation_matrix (array-like, shape = (3,3) or (4,4)) –
• translation (array-like[3]) – vector

Returns:

self.O (operator)

Return type:

numpy.matrix(shape = (4,4))

dfbydv(xyz, dfbydp)

Partial derivatives ∂f(p)/∂v, where f is a function of positions xyz.

Parameters:

• xyz (array-like shape = (3,natom).) – position column vector(s) BEFORE application of operator.
• dfbydp (array-like shape = (3,natom)) – column vectors each with a partial derivative of function f, with respect to the xyz coordinates of an atom position, p, AFTER application of the operator (i.e. ∂f/∂p).

Returns:

partial derivative of f(p)/∂v column vector(s) for each atom.

Return type:

ndarray.shape(3,natom)

Todo

Support input of a callable instead of ∂f/∂p array would resolve the confusion of coordinates before and after transformation.

Todo

return sum?

dpbydv(xyz)

Partial derivatives of position re: operator parameters, ∂p/∂v.

Parameters:xyz (array-like shape = (3,natom).) – p, position column vector(s) before application of operator. Returns:partial derivative column (or row?) vector(s) for each atom, for each component of v. Return type:ndarray, shape = (len(v), 3, natom)

eulerAxis(verbose=False)

Euler rotation and axis from operator matrix.

Parameters:verbose (bool) – print rotation & axis Returns:(rotation (degrees), unit-vector-axis) Return type:float, numpy.matrix.shape(3,1)

eulerX0Y0Z0(verbose=True)

Euler angles from operator matrix assuming R_XYZ fixed axes.

Returns:θ₁ (rad; 3^rd rotation about fixed X₀), θ₂ (about fixed Y₀), θ₃ (1^st rotation about fixed Z₀). Return type:(float, float, float)

See Bernard Rupp eqn. 11-11

isunit()

Returns:True if unit operator. Return type:bool

rotTrans()

Decompose augmented operator into rotation + translation.

sphericalPolarAngles(verbose=False)

Spherical Polar Angles from operator matrix.

Parameters:verbose (bool) – Returns:φ (rad. from X), ψ (rad. from Z), κ (rotation, rad.) Return type:float, float, float

class transform.EulerX0Y0Z0(matrix=None, rotation=None, origin=matrix([[ 0.], [ 0.], [ 0.]]), translation=None)

Bases: transform.AugmentedOperator

Matrix operator parameterized by Eulerian angles with X0Y0Z0 convention.

For θ = [t₁, t₂, t₃]:

t₃ (θ[2]) is 1st rotation (about fixed X) applied to coordinates; t₂ (θ[1]) (about fixed Y₀); t₁ (θ[0]; about fixed Z₀) is 3^rd rotation applied.

Variables:

• O – operator
• origin – for rotation, implicit in self.O, but needed for Jacobian
• dO – partial derivatives of O with respect to rotation vector and translation, currently assuming origin will be subtracted from coordinates, but may be able to extend to do this automatically.

Instantiate Operator O from Euler angles or pre-existing matrix.

Parameters:

• rotation (array-like[3]) – θ.
• origin (array-like(shape = 3)) – for rotation about something other than (0,0,0)
• translation (array-like[3]) –

dObydv

Partial derivatives of operator matrix re: each parameter, ∂O/∂v.

We seek ∂O/∂v for p‘ = O.p

Splitting O into rotation, R, about origin, o, plus subsequent translation, t:

• p‘ = R(p - o) + t + o
• ∂p‘/∂v = ∂R/∂v.p - ∂R/∂v.o

Thus, the effect of rotating about a non-zero origin can be accommodated in the 4^th column of ∂O/∂v with the dot product of the rotational derivative and the origin vector.

The matrix returned is sparse (40/96 non-zero elements), so might be more efficient to use 9-element rotation & handle origin/translations with vector additions.

Returns:∂O/∂v Return type:array (len(v) = 6,4,4)

dfbydv(xyz, dfbydp)

dpbydv(xyz)

class transform.Vector(matrix=None, rotation=None, origin=matrix([[ 0.], [ 0.], [ 0.]]), translation=None)

Bases: transform.AugmentedOperator

Matrix operator parameterized by rotation axis vector, length = radians.

(Brynmor’s parameterization.)

Variables:

• O – operator
• origin – for rotation, implicit in self.O, but needed for Jacobian
• dO – partial derivatives of O with respect to rotation vector and translation, currently assuming origin will be subtracted from coordinates, but may be able to extend to do this automatically.

Instantiate Operator O from vector or pre-existing matrix.

Parameters:

• rotation (array-like[3]) – vector along axis, length = rotation (radians).
• origin (array-like(shape = 3)) – for rotation about something other than (0,0,0)
• translation (array-like[3]) –

transform.compute_rigid_alignment_deriv(u, d, vt, rh)

Partial derivatives of alignment operator with respect to each element?

The alignment operator is used to rigidly superimpose an original set of coordinates on a target.

Module author: Brynmor K. Chapman.

Note

documentation written by Michael, with much guessing, and needs to be rewritten by Brynmor (!). Guessing that the 3x3 matrices may relate to the rotational component of the operator, and d to the translation.

Parameters:

• u (numpy.matrix(shape=(3,3))) –
• d (numpy.array(shape=(3,))) –
• vt (numpy.matrix(shape=(3,3))) –
• rh (numpy.matrix(shape=(3,3))) –

transform.compute_rigid_alignment_matrix(original, target, deriv=False)

Operator to superimpose original coordinates on target.

Operator is determined by Kabsch’s eigenvector method [Kabsch-1976], [Kabsch-1978].

The derivatives that are calculated can be chained to calculate partial derivatives that are invariant with respect to the overall rotation and translation.

Module author: Brynmor K. Chapman.

Note

Documentation guessed by Michael and needs to be checked by Brynmor.

Parameters:

• original (numpy.matrix(shape=(4,n)) – Augmented matrix, each column a coordinate position vector, with 1.0 in the final row.
• target (numpy.matrix(shape=(4,n)) – Augmented matrix, each column a coordinate position vector,
• deriv (bool) – return (flattened) derivative of operator with respect to each coordinate in original, flattened (I’m guessing) with natom * ∂x followed by natom * ∂y and natom * ∂z.

Returns:

operator [, derivatives]

Return type:

numpy.matrix(shape=(4,4) [, numpy.matrix(16, 3*natom)]

transform.compute_rotation_about_origin(v, angle=None, deriv=False)

Augmented 4x4 matrix for rotation about vector through origin.

Parameters:

• v (numpy.matrix(shape = (d, 1)) for d in {3,4}) – column vector about which right-hand rotation to be made, usually of length equal to the rotation (radians).
• angle (float) – optional explicit specification (radians) permitted only if not deriv.
• deriv (bool) – compute partial derivatives of matrix re vector components (or re x, y, z if |v| = 0).

Returns:

operator[, derivatives]

Return type:

numpy.matrix(shape(4,4)) [, ndarray(shape = (3,4,4))]

transform.compute_rotation_matrix(v1, v2, angle, deriv=False)

Augmented 4x4 matrix for rotation about axis from position v1 to v2.

Parameters:

• v1 (numpy.matrix(shape = (d, 1)) for d in {3,4}) – column position vector.
• v2 (numpy.matrix(shape = (d, 1)) for d in {3,4}) – column position vector.
• angle (float) – rotation (radians), right-handed from v1 to v2.
• deriv (bool) – compute derivative of matrix wrt angle.

Returns:

operator[, derivatives]

Return type:

numpy.matrix(shape(4,4)) [, numpy.matrix(shape = (4,4))]

transform.compute_transformation_matrix(params, deriv=False)

Augmented 4x4 rotation/translation matrix operator.

Parameters:

• params (ndarray(shape = 6)) – 1st 3 elements are vector of magnitude equal to the rotation (radians, right-handed) along the rotation axis. Next 3 elements are the translation applied after rotation.
• deriv (bool) – compute partial derivatives of matrix re vector components (or re x, y, z if |v| = 0).

Returns:

operator[, derivatives]

Return type:

numpy.matrix(shape(4,4)) [, ndarray(shape = (3,4,4))]

transform.displacements(points, params=None, operator=None, verbose=True)

Displacements of points transformed by params or operator.

Parameters:

• points (ndarray(shape = (3 or 4, natom)) – Coordinates as column vectors, optionally augmented with 4th row of ones.
• params (ndarray(shape = 6)) – as in compute_transformation_matrix
• operator (numpy.matrix(shape = 4,4)) – matrix operator equivalent to params to be applied as operator * points.

Returns:

difference vectors from initial points to transformed

Return type:

ndarray, like points

transform.dot(operator, vector)

Dot product of operator with column vector(s).

result = operator * vector. Polymorphic, accepting augmented (or not) vector for optionally augmented operator. Documentation below should be correct for 1D & 2D, but don’t understand how numpy.dot works for higher dimensions... will have to try.

Parameters:

• operator (ndarray, shape = (...,3) or (...,4)) –
• vector (ndarray, shape = (3,...) or (4,...) if operator is augmented) – Column vector(s).

Returns:

transformed coordinate column vector(s)

Return type:

ndarray, shape of vector

transform.general_transformation_matrix(params, origin=None, deriv=False)

Augmented 4x4 matrix for rotation about non-zero origin + translation.

Let:

• c be position vector for center of rotation.
• p be position vector for an individual point.
• Rc be operator for rotation about c.
• R₀ be operator for rotation about (0,0,0).
• t be translation component of operator.
• v be parametric description of the operator.

Rc.p = R₀(p - c) + t + c

Then (by intuition!):

∂p/∂Rc = ∂p/∂R₀ - ∂c/∂R₀

This function returns Rc [and ∂Rc/∂v]

Parameters:

• params (ndarray(shape = 6)) – 1st 3 elements are vector of magnitude equal to the rotation (radians, right-handed) along the rotation axis. Next 3 elements is the translation applied after rotation.
• origin (numpy.matrix(shape = (3,1))) – center of rotation (or None for 0,0,0).
• deriv (bool) – compute partial derivatives of matrix re vector components (or re x, y, z if |v| = 0).

Returns:

operator[, derivatives], i.e. Rc [and ∂Rc/∂v]

Return type:

numpy.matrix(shape(4,4)) [, ndarray(shape = (3,4,4))]

Changed in version 9/1/12: from Brynmor’s original by Michael.

transform.groupPartials(xyz, selection, dGbydp, groupParams, groupOperator, rotateAbout=None, *positional, **named)

Partial derivatives re rigid group parameters from partials re positions.

Applies chain rule, typically to calculate partials of residual with respect to the orientation and translation of a group of atoms.

∂Γ/∂v = ∂Γ/∂p . ∂p/∂v = (∂Γ/∂p)(∂Vp₀/∂v) = (∂Γ/∂p)(∂V/∂v).p₀

Parameters:

• xyz (numpy.matrix(shape = (3,natom))) – Original atomic coordinates, before application of groupOperator(s).
• selection (class Selection (or ndarray(dtype=bool, shape=natom)) – True for atoms belonging to the group.
• dGbydp (numpy.matrix(shape = (3,natom))) – Partial derivatives (of a residual, Γ) with respect to Cartesian atomic position vectors, ∂Γ/∂p.
• groupParams (ndarray) – Group parameters (v), should be general for any parameterization, but tested with params as in compute_transformation_matrix.
• groupOperator (callable) – Method that returns 4x4 Cartesian group operator, V, from groupParams (as its 1^st argument), and its partial derivatives with respect to components of v, eg. group_transformation_matrix.
• rotateAbout (ndarray(shape=3) or NoneType) – Point about which rotations made (or 0,0,0 if None).
• positional (list) – additional positional arguments to be passed to groupOperator.
• named (dict) – additional named arguments to be passed to groupOperator.

Returns:

partial derivatives with respect to group parameters ∂Γ/∂v (summed over atoms of the group).

Return type:

numpy.matrix(len(v),1)

Module author: Michael S. Chapman

Todo

if comRotations moved w/in groupOperator, rotateAbout would be passed through **named.

transform.groupTransformations(xyz, selections, groupsParams, groupOperator, anisotropics=None, comRotations=False, *positional, **named)

Transform xyz by list of group operators for list of atom selections.

Parameters:

• xyz (numpy.matrix(shape = (3,natom))) – Starting atomic coordinates.
• selections (list(class Selection | ndarray(dtype=bool, shape=natom))) – True for atoms belonging to each group.
• groupsParams (list(ndarray)) – Group parameters (v) for each group, general for any parameterization, but tested with compute_transformation_matrix().
• groupOperator (callable) – Method that returns 4x4 Cartesian group operator, O, with groupsParams[i] as 1^st argument.
• anisotropics (Anisotropics/NoneType) – U-values if to be transformed.
• comRotations (bool) – Rotations to be about selection center of masses.
• positional (list) – additional positional arguments to be passed to groupOperator.
• named (dict) – additional named arguments to be passed to groupOperator.

Returns:

transformed coordinates.

Return type:

numpy.matrix(shape = (3, natom))

Module author: Michael S. Chapman

Todo

if comRotations moved w/in groupOperator, it would be passed within **named.

transform.multiply_matrix_array(a, b, big=True, out=None)

Matrix dot product, arbitrary dimensionality, polymorphic.

Module author: Brynmor K. Chapman (primary)

Module author: Michael S. Chapman (optimization)

Parameters:

• big (bool) – optimization appropriate for large b-matrix (might be less efficient for small b).
• out – optional array used for efficiency to return the result. If given, must be C-contiguous and of same type/shape as returned by this function. I have not yet found a situation where this actually improves efficiency. If you want to try, suggest calling w/ out=None to find the shape, and then inserting out. Should throw exception if incorrect. If the result is overwriting a calling argument, take case as it seems possible that specification of out might over-write elements of array.

Returns:

dot-product matrix

Return type:

numpy.array

transform.non_zero(a)

Determine if not close to zero.

Module author: Brynmor K. Chapman.

Returns:True if value >= 2 * machine precision. Return type:bool or numpy.array(dtype=bool)

transform.random_rotation_about_origin()

Augmented 4x4 matrix for random rotation through origin.

Returns:operator Return type:numpy.matrix(shape(4,4))

transform.testFunction(xyz)

Simple objective function and partials. Square distance from point.

Parameters:xyz (ndarray.shape(3,natom)) – Returns:function, partial derivatives Return type:float, ndarray.shape(3,atom)

transform.trial(selection_criteria, rotations, translations, seed=None, verbose=True)

Randomized test data- rotations are magnitudes (degrees).

transform.zero(a)

True if smaller than number close to machine precision.