Quaternions

The Quaternion class

class quaternions.Quaternion(real_component: float = 0.0, i_component: float = 0.0, j_component: float = 0.0, k_component: float = 0.0)

Quaternions are an expansion of the complex numbers, where there are four (4) components–the real component, also known as the scalar part, and the imaginary components, which together are known as the vector part. The vector part is made up of three (3) components whose unit values are i, j, and k. The rules for these values are as follows:

\(i^2 = j^2 = k^2 = -1\)

\(jk = -kj = i\)

\(ki = -ik = j\)

\(ij = -ji = k\),

which leads to the following statement:

\(ijk = -1\).

The descriptions will reference a quaternion of the form \(a + bi + cj + dk\), where \(a\), \(b\), \(c\), and \(d\) are real numbers.

Parameters:

real_component – The real component (\(a\)) of the quaternion.
i_component – The i component (\(b\)) of the quaternion.
j_component – The j component (\(c\)) of the quaternion.
k_component – The k component (\(d\)) of the quaternion.

Each component can be returned by calling the attribute of the same name.

Example

>>> q = Quaternion(1, -2, -3, 4)
>>> print(q)
(1 - 2i - 3j + 4k)
>>> q.real
1.0
>>> q.i
-2.0
>>> q.j
-3.0
>>> q.k
4.0

Methods

Object-based methods

Quaternion.abs_components(): Return a list of the absolute values of the components of self.

New in version 2.0.0.

Quaternion.from_complex(z: complex) → Quaternion

Return a Quaternion from a complex number and the vector of self.

If u == self.unit_vector(), this is equivalent to

Quaternion(z.real, z.imag*u.i, z.imag*u.j, z.imag*u.k)

New in version 2.0.0.

Quaternion.get_imag() → float: Return the imaginary component of the quaternion if only one of the imaginary components is nonzero. If the quaternion is scalar, return 0.0. Otherwise, return None.

Quaternion.get_vector_components() → Tuple[float]: Return the vector components of the Quaternion as a tuple formatted as (i, j, k).

Mathematical methods

Quaternion.conjugate() → Quaternion: Return the conjugate of self. This is analogous to the complex conjugate, reversing the signs of the vector components.

Quaternion.inverse() → Quaternion

Return 1/self.

Return the inverse of the quaternion. The inverse of a quaternion is defined as the conjugate divided by the norm squared:

q.inverse() = q.conjugate()/(q.norm)**2

Quaternion.squared() → Quaternion: Return self**2.

New in version 2.0.0.

Quaternion.cos_norm() → float: Return the cosine of the norm of self.

New in version 2.0.0.

Quaternion.sin_norm() → float: Return the sine of the norm of self.

New in version 2.0.0.

Quaternion.log_norm() → float

Return the natural logarithm of the norm of self.

This tends to be more accurate than

>>> math.log(self.norm)

New in version 2.0.0.

Quaternion.unit_quaternion() → Quaternion

Return the quaternion normalized to magnitude one (1).

If the quaternion is a zero (0) quaternion, return the zero quaternion.

Quaternion.unit_vector() → Quaternion: Return the vector part of the quaternion normalized to a magnitude of one (1.0). Return the zero quaternion if the magnitude of the quaternion is zero (0.0).

Boolean methods

Quaternion.is_complex() → bool: Return True if only one of the i, j, and k components is nonzero. Otherwise, return False.

Quaternion.is_scalar() → bool: Return True if the vector components all equal zero. Otherwise, return False.

Quaternion.is_vector() → bool: Return True if the scalar part is zero and at least one of the vector components is nonzero. Otherwise, return False.

Quaternion.is_zero() → bool: Return True if self is the zero quaternion. Otherwise, return False.

New in version 2.0.0.

Quaternion.is_not_zero() → bool: Return False if self is the zero quaternion. Otherwise, return True.

New in version 2.0.0.

Class methods

classmethod Quaternion.from_angle(angle: float, vector: Iterable[float], norm: Optional[float] = None, degrees: bool = True) → Quaternion

Return a quaternion from an angle and vector.

Quaternions can be expressed as norm*(cos(theta) + u*sin(theta)), where u is a 3D unit vector. This function takes an angle and a vector to create a quaternion. If you want a quaternion with a specific magnitude, you can change the norm argument. If no argument is given for norm, the resulting quaternion will have a norm equal to the magnitude of vector. By default, angles are entered in degrees. If you want to enter an angle in radians, set degrees to False.

Properties

property Quaternion.angle: float: The angle of the quaternion in radians.

property Quaternion.angle_in_radians: Same as Quaternion.angle

property Quaternion.angle_in_degrees: float: The angle of the quaternion in degrees.

property Quaternion.components: Tuple[float]: The components of the quaternion as a tuple in the order (real, i, j, k).

property Quaternion.norm: float: The norm (magnitude) of the quaternion.

property Quaternion.scalar: Quaternion: The real part of the quaternion.

property Quaternion.vector: Quaternion: The vector part of the quaternion.

property Quaternion.vector_norm: float: The norm of the vector part of the quaternion.

property Quaternion.versor: Quaternion: The quaternion normalized to a magnitude of one (1).