euler

Changed in version 2.0.0

This section and the functions experinced major revision in version 2.0.0. Some functions in versions 1.X.X do not produce the correct results due to sign and matrix element assignment error. This has been corrected.

This module provides conversion functions for the EFG euler angles and their directions in the internal coordinate system.

The definiton of the Euler angles \(\alpha, \beta, \gamma\) in Nexus is such that they rotate the EFG to the internal coordinate system in ZYZ convention [Sturhahn]. Nexus works with an internal coordinate system of \((\sigma, \pi, k)\). There are several ways to rotate the EFG coordinate system to the internal coordinate systems (intrinisic or extrinsic, active or passive).

In general a rotation matrix R rotates the vector \(v\) in the coordinate system to the new position \(v' = R v\). To reach every point in space, the rotation matrix is a composition of three basic rotations and described by the Euler angles \(\alpha, \beta, \gamma\)

\[R = R_x(\alpha) R_y(\beta) R_z(\gamma)\]

where x,y,z are the axes of rotations. This matrix rotates one coordinate system to another coordinate system (e.g EFG frame and internal frame). This can either be an intrinsic rotations around the rotated body axes x-y’-z’’ (in that order) or extrinsic rotations around the fixed coordinate system axes Z-Y-X (in that order).

This rotation is described by a rotation matrix \(R=R_z(\alpha) R_y(\beta) R_z(\gamma)\) consisting of three individual rotations around the three Euler angles. The order of rotations is for:

  • Intrinsic rotation of the rotating EFG frame to the fixed internal reference frame:

    1. Rotation by \(\alpha\) around axis \(z\) in the EFG frame.

    2. Rotation by \(\beta\) around new axis \(y'\) in the rotated EFG frame.

    3. Rotation by \(\gamma\) around new axis \(z''\) in the rotated EFG frame.

  • Extrinsic rotation of the EFG in the fixed internal reference frame:

    1. Rotation by \(\gamma\) around axis \(k\) in the fixed internal frame.

    2. Rotation by \(\beta\) around axis \(\pi\) in the fixed internal frame.

    3. Rotation by \(\alpha\) around axis \(k\) in the fixed internal frame.

To obtain the angles one has to start with the EFG in the final position and find the angles that rotate the EFG to internal coordinate system.

There is another approach that can be more intuitive. Here, one starts with the EFG aligned to the internal reference frame and the EFG is rotated away to the final position. This corresponds to the inverse rotation and will provide the inverse angles. For the rotation matrices \(R^{-1} = R^T\) and the inverse rotation is

\[\begin{split}\begin{array}{ccl} R^{-1} & = & \left( R_z(\alpha) R_y(\beta) R_z(\gamma) \right)^T \\ & = & R_z(\gamma)^T R_y(\beta)^T R_z(\alpha)^T \\ & = & R_z(-\gamma) R_y(-\beta) R_z(-\alpha) \end{array}\end{split}\]

The order of rotations change and one obtains the inverse rotation around the axes. For an extrinsic rotation of the EFG (initially aligned to the reference frame) to its final orientation, the order is:

  1. Rotation by \(\alpha\) around axis \(k\) in the fixed internal frame.

  2. Rotation by \(\beta\) around axis \(\pi\) in the fixed internal frame.

  3. Rotation by \(\gamma\) around axis \(k\) in the fixed internal frame.

From the above it follows that the instrinsic rotation of the final EFG position to the internal reference frame and the extrinsic rotation from the initailly algined EFG to the final EFG positon have the same order: First by \(\alpha\), then by \(\beta\), then by \(\gamma\), however, with inverted signs.

The module provides functions to get the EFG orientation from the Euler angles and vice versa. Please also have a look to the tutorial section for an explanation of the order of rotations.

See also

https://en.wikipedia.org/wiki/Euler_angles

nexus.euler.AnglesToVectors(alpha: float, beta: float, gamma: float, rotation: str = 'intrinsicEFG')

Calculates the EFG vectors corresponding to the Euler angles in ZYZ convention. Input the ZYZ Euler angles to obtain Vx, Vy, Vz.

Parameters:

  • alpha (float) – Euler angle \(\alpha\) (rad).

  • beta (float) – Euler angle \(\beta\) (rad).

  • gamma (float) – Euler angle \(\gamma\) (rad).

  • rotation (string) –

    Defines the rotation convention.

    • intrinsicEFG: Euler angles in the definition of an intrinsic rotation of the EFG orientation to the internal coordinate system.

    • extrinsicINT: Euler angles in the definition of an extrinsic rotation of the EFG away from the internal coordinate system.

Returns:

Vx, Vy, Vz

Return type:

ndarray, ndarray, ndarray

nexus.euler.RotationMatrix3D(Ra, Rb, Rc)

Returns the 3x3 rotation matrix from three rotation matrices. For an active rotation the function applies the 3 transformations in the order:

\[R = R_a(\alpha) R_a(\beta) R_c(\gamma)\]

Where \(a, b, c\) represent an axes of rotation, so for example \(a=Z, b=Y, c=Z\) for ZYZ convention of the Euler angles.

The order of rotations of an active rotation corresponds to the two following cases:

  • Extrinsic rotation in the fixed frame:

    1. Rotation with \(R_c\) by angle \(\gamma\).

    2. Rotation with \(R_b\) by angle \(\beta\).

    3. Rotation with \(R_a\) by angle \(\alpha\).

  • Intrinsic rotation of the rotating body:

    1. Rotation by \(\alpha\) around axis \(a\) in the body frame.

    2. Rotation by \(\beta\) around new axis \(b'\) in the rotated body frame.

    3. Rotation by \(\gamma\) around new axis \(c''\) in the rotated body frame.

Here, an example for a rotation in ZYZ convention

Ra = RotationZ(alpha)
Rb = RotationY(beta)
Rc = RotationZ(gamma)

R = ZYZEulerToTransformationMatrixFromRotationMatrix(Ra, Rb, Rc)
Parameters:

  • Ra (2D array) – 3x3 rotation matrix around axis \(a\) by \(\alpha\) (rad).

  • Rb (2D array) – 3x3 rotation matrix around axis \(b\) by \(\beta\) (rad).

  • Rc (2D array) – 3x3 rotation matrix around axis \(c\) by \(\gamma\) (rad).

Returns:

3x3 rotation matrix.

Return type:

ndarray

nexus.euler.RotationVector(angle: float, vector)

Returns the rotation matrix for a rotation by angle around an arbitrary vector. Rotations appear counterclockwise when the axis about which they occur points toward the observer.

Added in version 2.0.0.

Parameters:

  • angle (float) – rotation angle (rad).

  • vector (list or ndarray) – 3 component vector.

Returns:

3x3 rotation matrix.

Return type:

ndarray

nexus.euler.RotationX(angle: float)

Returns the rotation matrix for a rotation by angle around the X axis of the internal coordinate system. Rotations appear counterclockwise when the axis about which they occur points toward the observer.

Changed in version 2.0.0: Active rotation now. In versions 1.X.X a passive rotation was used.

Parameters:

angle (float) – rotation angle (rad).

Returns:

3x3 rotation matrix.

Return type:

ndarray

nexus.euler.RotationY(angle: float)

Returns the rotation matrix for a rotation by angle around the Y axis of the internal coordinate system. Rotations appear counterclockwise when the axis about which they occur points toward the observer.

Changed in version 2.0.0: Active rotation now. In versions 1.X.X a passive rotation was used.

Parameters:

angle (float) – rotation angle (rad).

Returns:

3x3 rotation matrix.

Return type:

ndarray

nexus.euler.RotationZ(angle: float)

Returns the rotation matrix for a rotation by angle around the Z axis of the internal coordinate system. Rotations appear counterclockwise when the axis about which they occur points toward the observer.

Changed in version 2.0.0: Active rotation now. In versions 1.X.X a passive rotation was used.

Parameters:

angle (float) – rotation angle (rad).

Returns:

3x3 rotation matrix.

Return type:

ndarray

nexus.euler.TransformationMatrixToEFGvectors(T)

Returns the row vectors from the transformation matrix T. Input the transformation matrix of the EFG components from ZYZEulerToTransformationMatrix to obtain Vx, Vy, Vz. \(V_i\) is a row vector, e.g. \(V_x = (V_{xx}, V_{xy}, V_{xz})\).

Parameters:

T (ndarray) – 3x3 transformation matrix.

Returns:

Vx, Vy, Vz (row vectors)

Return type:

ndarray, ndarray, ndarray

nexus.euler.TransformationMatrixToZYZEuler(T, rotation: str = 'intrinsicEFG')

Returns the Euler angles from a 3x3 transformation with respect to the internal coordinate system \((\sigma, \pi, k)\).

Changed in version 2.0.0: In versions 1.X.X the Euler angles for the active rotation were calcualted.

Note

For certain rotation matrices several sets of angular combinations exist. In case you do not obtain the angles you expect, please check if they lead to the same rotation marix.

Parameters:

  • T (ndarray) – 3x3 array.

  • rotation (string) –

    Defines the rotation convention.

    • intrinsicEFG: Euler angles in the definition of an intrinsic rotation of the EFG orientation to the internal coordinate system.

    • extrinsicINT: Euler angles in the definition of an extrinsic rotation of the EFG away from the internal coordinate system.

Returns:

alpha, beta, gamma (rad)

Return type:

float, float, float

nexus.euler.VectorsToAngles(Vz, Vx=None, Vy=None, rotation: str = 'intrinsicEFG')

Calculates the Euler angles corresponding to the EFG vectors in their internal coordinate system. Input 3 orthogonal vectors of the EFG components Vx, Vy, and Vz in the internal coordinate system or just the main component Vz. V_i is a row vector, e.g. \(V_x = (V_{xx}, V_{xy}, V_{xz})\). When you only provide the Vz it is assumed that the asymmetry parameter is zero and the orientations of Vx and Vy are unimportant. The vectors muts be orthogonal and will be normalized, so only their directions matter.

E.g. Vx = [0,0,1], Vy = [-1,-1,0], Vz = [1,-1,0] in the \((\sigma, \pi, k)\) coordinate system.

Note

In case only the main axis Vz is given, the returned \(\alpha\) value is random.

Changed in version 2.0.0: In case only the main axis Vz is given, only the sum \(\alpha + \gamma\) is defined. The function returns \(\alpha=0\) and \(\gamma\) is defined by the Vz[0] and Vz[1] components.

Parameters:

  • Vx (ndarray) – Vx vector in the reference frame.

  • Vy (ndarray) – Vy vector in the reference frame.

  • Vz (ndarray) – Vz vector in the reference frame.

  • rotation (string) –

    Defines the rotation convention.

    • intrinsicEFG: Euler angles in the definition of an intrinsic rotation of the EFG orientation to the internal coordinate system.

    • extrinsicINT: Euler angles in the definition of an extrinsic rotation of the EFG away from the internal coordinate system.

Returns:

\(\alpha\) (rad), \(\beta\) (rad), \(\gamma\) (rad)

Return type:

float, float, float

nexus.euler.ZYZEulerToTransformationMatrix(alpha: float, beta: float, gamma: float, rotation: str = 'intrinsicEFG')

Returns the 3x3 transformation matrix from Euler angles of the EFG in ZYZ convention. The total matrix \(R = R_k(\alpha)R_{\pi}(\beta)R_k(\gamma)\) is

\[\begin{split}R = \begin{pmatrix} \cos(\alpha) \cos(\beta) \cos(\gamma) - \sin(\alpha) \sin(\gamma) & -\cos(\gamma) \sin(\alpha) - \cos(\alpha) \cos(\beta) \sin(\gamma) & \cos(\alpha) \sin(\beta) \\ \cos(\alpha) \sin(\gamma) + \cos(\beta) \cos(\gamma) \sin(\alpha) & \cos(\alpha) \cos(\gamma) - \cos(\beta) \sin(\alpha) \sin(\gamma) & \sin(\alpha) \sin(\beta) \\ -\cos(\gamma) \sin(\beta) & \sin(\beta) \sin(\gamma) & \cos(\beta) \end{pmatrix}\end{split}\]

Changed in version 2.0.0: Active rotation now. In versions 1.X.X a passive rotations was used.

Parameters:

  • alpha (float) – Euler angle \(\alpha\) (rad).

  • beta (float) – Euler angle \(\beta\) (rad).

  • gamma (float) – Euler angle \(\gamma\) (rad).

  • rotation (string) –

    Defines the rotation convention.

    • intrinsicEFG: Euler angles in the definition of an intrinsic rotation of the EFG orientation to the internal coordinate system.

    • extrinsicINT: Euler angles in the definition of an extrinsic rotation of the EFG away from the internal coordinate system.

Returns:

3x3 transformations matrix for ZYZ Euler angles.

Return type:

ndarray

nexus.euler.ZYZEulerToTransformationMatrixExtrinsic(alpha, beta, gamma)

Removed in version 2.0.0: Wrong matrix in verions 1.X.X

Returns the 3x3 transformation matrix from extrinsic Euler angles of the EFG to rotate to the internal coordinate system. The function applies the three different rotations after each other in the order:

  • Rotation around Z by \(\gamma\).

  • Rotation around Y by \(\beta\).

  • Rotation around Z by \(\alpha\).

Euler angles in extrinsic ZYZ convention.

Parameters:

  • alpha (float) – Euler angle \(\alpha\) (rad).

  • beta (float) – Euler angle \(\beta\) (rad).

  • gamma (float) – Euler angle \(\gamma\) (rad).

Returns:

3x3 transformations matrix.

Return type:

ndarray

nexus.euler.ZYZEulerToTransformationMatrixIntrinsic(alpha, beta, gamma)

Removed in version 2.0.0: Wrong matrix in verions 1.X.X

Returns the 3x3 transformation matrix from intrinsic Euler angles of the EFG to rotate to the internal coordinate system. The function applies the three different rotations after each other in the order:

  • Rotation around Z by \(\alpha\).

  • Rotation around new internal Y’ by \(\beta\).

  • Rotation around new internal Z’’ by \(\gamma\).

Euler angles in intrinsic ZYZ convention.

Parameters:

  • alpha (float) – Euler angle \(\alpha\) (rad).

  • beta (float) – Euler angle \(\beta\) (rad).

  • gamma (float) – Euler angle \(\gamma\) (rad).

Returns:

3x3 transformations matrix.

Return type:

ndarray