sisl.Quaternion

class sisl.Quaternion

Bases: object

Quaternion object to enable easy rotational quantities.

The rotation using quaternions amounts to a rotation around a vector \(v\) by an angle \(\phi\).

The rotation follows the Euler-Rodrigues formula.

The components of the quaternion will be referenced as:

\[a + b\mathbf i + c\mathbf j + d\mathbf k\]

The general way this gets translated is the complex matrix:

\[\begin{split}\begin{bmatrix} a + b i & c + d i\\ -c + d i & a - b i \end{bmatrix}\end{split}\]

Parameters:

• *args – For 1 argument, it is the length 4 vector describing the quaternion. For 2 arguments, it is the angle, and vector.

• rad – when passing two arguments, for angle and vector, the rad value decides which unit angle is in, for rad=True it is in radians. Otherwise it will be in degrees.

Examples

Construct a quaternion with angle 45°, all 3 are equivalent:

>>> q1 = Quaternion(45, [1, 2, 3], rad=False)
>>> q2 = Quaternion(np.pi/4, [1, 2, 3], rad=True)
>>> q3 = Quaternion([1, 2, 3], 45, rad=False)

If you have the full quaternion complex number, one can also instantiate it directly without having to consider angles:

>>> q = Quaternion([1, 2, 3, 4])

Methods

angle([rad])	Return the angle of this quaternion, in requested unit
conj()	Returns the conjugate of the quaternion
copy()	Return a copy of itself
norm()	Returns the norm of this quaternion
norm2()	Returns the squared norm of this quaternion
rotate(v)	Rotate a vector v by this quaternion
rotation_matrix()	Determine the Cartesian rotation matrix from the quaternion
rotation_matrix_su2()	Returns the special unitary group 2 rotation matrix.
rotation_vector()	Retrieve the vector the rotation rotates about

Attributes

degree	Returns the angle associated with this quaternion (in degrees)
radian	Returns the angle associated with this quaternion (in radians)

angle(rad=True)

Return the angle of this quaternion, in requested unit

Parameters:

rad (bool)

Return type:

float

conj()

Returns the conjugate of the quaternion

Return type:

Quaternion

copy()

Return a copy of itself

Return type:

Quaternion

norm()

Returns the norm of this quaternion

Return type:

float

norm2()

Returns the squared norm of this quaternion

Return type:

float

rotate(v)

Rotate a vector v by this quaternion

This rotation method uses the fast method which can be expressed as:

\[\mathbf v' = \mathbf q \mathbf v \mathbf q ^*\]

But using a faster approach (more numerically stable), we can use this relation:

\[\begin{split}\mathbf t = 2\mathbf q \cross \mathbf v \\ \mathbf v' = \mathbf v + q_w \mathbf t + \mathbf q \cross \mathbf t\end{split}\]

Return type:

ndarray

rotation_matrix()

Determine the Cartesian rotation matrix from the quaternion

Examples

Rotate a list of coordinates (same as Quaternion.rotate(xyz)) >>> q = Quaternion(…) >>> xyz = np.random.rand(4, 3) >>> U = q.rotation_matrix() >>> xyz_rotated = U @ xyz

Return type:

ndarray

rotation_matrix_su2()

Returns the special unitary group 2 rotation matrix.

The SU(2) group defines the unitary group encompassing spin matrices enables one to rotate the spin-block-matrices.

The quaternion can directly be translated to the 2x2 matrix defining the rotation of the spin-block matrix:

\[U = a \mathbf I - ib\sigma_x - ic\sigma_y -id\sigma_z\]

Notes

This implementation uses the alternate representation.

\[\begin{split}\begin{bmatrix} a - d i & -c - b i\\ c - b i & a + d i \end{bmatrix}\end{split}\]

Examples

Rotate a spin-block matrix >>> q = Quaternion(…) >>> m = np.random.rand(3, 2, 2) >>> U = q.rotation_matrix_su2() >>> m_rotated = U @ m @ U.T.conj()

Return type:

ndarray

rotation_vector()

Retrieve the vector the rotation rotates about

Return type:

ndarray

property degree: float

Returns the angle associated with this quaternion (in degrees)

property radian: float

Returns the angle associated with this quaternion (in radians)