quaternionic.arrays

Class array

array(input_array, *args, **kwargs)

Source: quaternionic/arrays.py

Subclass of numpy arrays interpreted as quaternions. This class encapsulates quaternion algebra, with numpy's "ufunc"s overridden by quaternionic methods. Standard algebraic operations can be performed naturally — as in q1+q2, q1*q2, etc. Numpy functions can also be used as expected — as in np.exp(q), np.log(q), etc. Because this is a subclass of numpy's ndarray object, its constructor takes anything the ndarray constructor takes, or just an ndarray to be re-interpreted as a quaternion array: q1 = quaternionic.array([1, 2, 3, 4]) # explicit array q2 = quaternionic.array(np.random.normal(size=(10, 4)) # re-interpret ndarray In addition to the basic numpy array features, we also have a number of extra properties that are particularly useful for quaternions, including * Methods to extract and/or set components * w, x, y, z * i, j, k (equivalent to x, y, z) * scalar, vector (equivalent to w, [x, y, z]) * real, imag (equivalent to scalar, vector) * Methods related to norms * abs (square-root of sum of squares of components) * norm (sum of squares of components) * modulus, magnitude (equal to abs) * absolute_square, abs2, mag2 (equal to norm) * normalized * conjugate, conj * inverse * Methods related to array infrastructure * ndarray * flattened * iterator There are also several converters to and from other representations of rotations, including * to/from_rotation_matrix * to_transformation_matrix * to/from_axis_angle * to/from_euler_angles * to/from_spherical_coordinates

Attributes

Methods

abs

abs

Source: quaternionic/properties.py

The absolute value of the quaternion. This quantity is the square-root of the sum of the squares of the components of each quaternion. See the note in norm for the difference between this function and that. Basically, this is the square-root of that function.

abs2

abs2

Source: quaternionic/properties.py

The (Cayley) norm of the quaternion. This quantity is the sum of the squares of the components of the quaternion — equal to the square of the absolute value. Note that it may be surprising to find that this "norm" does not include the usual square root. This is conventional. For example, the Boost library's implementation of quaternions also uses this convention. Similarly, the implementation of complex numbers in C++ defines the abs and norm functions in this way, while python and numpy only define abs. If you are uncomfortable with this choice of the meaning of norm, it may make more sense to use one of the aliases of this function, which include * absolute_square * abs2 * mag2

absolute_square

absolute_square

Source: quaternionic/properties.py

The (Cayley) norm of the quaternion. This quantity is the sum of the squares of the components of the quaternion — equal to the square of the absolute value. Note that it may be surprising to find that this "norm" does not include the usual square root. This is conventional. For example, the Boost library's implementation of quaternions also uses this convention. Similarly, the implementation of complex numbers in C++ defines the abs and norm functions in this way, while python and numpy only define abs. If you are uncomfortable with this choice of the meaning of norm, it may make more sense to use one of the aliases of this function, which include * absolute_square * abs2 * mag2

flattened

flattened

Source: quaternionic/properties.py

A view of this array with all but the last dimension combined into one

i

i

Source: quaternionic/properties.py

The second component of the quaternion (rotation about x)

imag

imag

Source: quaternionic/properties.py

The "vector" part of the quaternion (final three components). Note that it is entirely standard to describe this part of the quaternion as the "vector" part. It would be more correct to refer to it as the "bivector" part, as explained by geometric algebra.

inverse

inverse

Source: quaternionic/properties.py

The multiplicative inverse of this quaternion

iterator

iterator

Source: quaternionic/properties.py

Iterate over all but the last dimension of this quaternion array

j

j

Source: quaternionic/properties.py

The third component of the quaternion (rotation about y)

k

k

Source: quaternionic/properties.py

The fourth component of the quaternion (rotation about z)

mag2

mag2

Source: quaternionic/properties.py

The (Cayley) norm of the quaternion. This quantity is the sum of the squares of the components of the quaternion — equal to the square of the absolute value. Note that it may be surprising to find that this "norm" does not include the usual square root. This is conventional. For example, the Boost library's implementation of quaternions also uses this convention. Similarly, the implementation of complex numbers in C++ defines the abs and norm functions in this way, while python and numpy only define abs. If you are uncomfortable with this choice of the meaning of norm, it may make more sense to use one of the aliases of this function, which include * absolute_square * abs2 * mag2

magnitude

magnitude

Source: quaternionic/properties.py

The absolute value of the quaternion. This quantity is the square-root of the sum of the squares of the components of each quaternion. See the note in norm for the difference between this function and that. Basically, this is the square-root of that function.

modulus

modulus

Source: quaternionic/properties.py

The absolute value of the quaternion. This quantity is the square-root of the sum of the squares of the components of each quaternion. See the note in norm for the difference between this function and that. Basically, this is the square-root of that function.

ndarray

ndarray

Source: quaternionic/properties.py

View this array as a numpy ndarray

norm

norm

Source: quaternionic/properties.py

The (Cayley) norm of the quaternion. This quantity is the sum of the squares of the components of the quaternion — equal to the square of the absolute value. Note that it may be surprising to find that this "norm" does not include the usual square root. This is conventional. For example, the Boost library's implementation of quaternions also uses this convention. Similarly, the implementation of complex numbers in C++ defines the abs and norm functions in this way, while python and numpy only define abs. If you are uncomfortable with this choice of the meaning of norm, it may make more sense to use one of the aliases of this function, which include * absolute_square * abs2 * mag2

normalized

normalized

Source: quaternionic/properties.py

The normalized version of this quaternion

real

real

Source: quaternionic/properties.py

The first (scalar) component of the quaternion

scalar

scalar

Source: quaternionic/properties.py

The first (scalar) component of the quaternion

to_axis_angle

to_axis_angle

Source: quaternionic/converters.py

Convert input quaternion to the axis-angle representation. Note that if any of the input quaternions has norm zero, no error is raised, but NaNs will appear in the output.

Returns

  • rot: float array

    Output shape is q.shape[:-1]+(3,). Each vector represents the axis of the rotation, with norm equal to the angle of the rotation in radians.

to_euler_angles

to_euler_angles

Source: quaternionic/converters.py

Open Pandora's Box. If somebody is trying to make you use Euler angles, tell them no, and walk away, and go and tell your mum. You don't want to use Euler angles. They are awful. Stay away. It's one thing to convert from Euler angles to quaternions; at least you're moving in the right direction. But to go the other way?! It's just not right. Assumes the Euler angles correspond to the quaternion R via R = exp(alphaz/2) * exp(betay/2) * exp(gammaz/2) The angles are naturally in radians. NOTE: Before opening an issue reporting something "wrong" with this function, be sure to read all of the following page, especially* the very last section about opening issues or pull requests. https://github.com/moble/quaternion/wiki/Euler-angles-are-horrible

Returns

  • alpha_beta_gamma: float array

    Output shape is q.shape+(3,). These represent the angles (alpha, beta, gamma) in radians, where the normalized input quaternion represents exp(alpha*z/2) * exp(beta*y/2) * exp(gamma*z/2).

to_euler_phases

to_euler_phases

Source: quaternionic/converters.py

Convert input quaternion to complex phases of Euler angles

Returns

  • z: complex array

    For each quaternion in the input array, this array contains the complex phases (zₐ, zᵦ, zᵧ) in that order. The shape of this output array is self.shape[:-1]+(3,).

!!! note We define the Euler phases from the Euler angles (α, β, γ) as zₐ ≔ exp(iα) zᵦ ≔ exp(iβ) zᵧ ≔ exp(i*γ) These are more useful geometric quantites than the angles themselves — being involved in computing spherical harmonics and Wigner's 𝔇 matrices — and can be computed from the components of the corresponding quaternion algebraically (without the use of transcendental functions).

to_rotation_matrix

to_rotation_matrix

Source: quaternionic/converters.py

Convert quaternions to 3x3 rotation matrices. Assuming the quaternion R rotates a vector v according to v' = R * v * R⁻¹, we can also express this rotation in terms of a 3x3 matrix ℛ such that v' = ℛ * v. This function returns that matrix.

Returns

  • rot: float array

    Output shape is self.shape[:-1]+(3,3). This matrix should multiply (from the left) a column vector to produce the rotated column vector.

to_rotation_vector

to_rotation_vector

Source: quaternionic/converters.py

Convert input quaternion to the axis-angle representation. Note that if any of the input quaternions has norm zero, no error is raised, but NaNs will appear in the output.

Returns

  • rot: float array

    Output shape is q.shape[:-1]+(3,). Each vector represents the axis of the rotation, with norm equal to the angle of the rotation in radians.

to_scalar_part

to_scalar_part

Source: quaternionic/converters.py

The "scalar" part of the quaternion (first component).

to_spherical_coordinates

to_spherical_coordinates

Source: quaternionic/converters.py

Return the spherical coordinates corresponding to this quaternion. Obviously, spherical coordinates do not contain as much information as a quaternion, so this function does lose some information. However, the returned spherical coordinates will represent the point(s) on the sphere to which the input quaternion(s) rotate the z axis.

Returns

  • vartheta_varphi: float array

    Output shape is q.shape+(2,). These represent the angles (vartheta, varphi) in radians, where the normalized input quaternion represents exp(varphi*z/2) * exp(vartheta*y/2), up to an arbitrary inital rotation about z.

to_transformation_matrix

to_transformation_matrix

Source: quaternionic/converters.py

Convert quaternions to 4x4 transformation matrices. Assuming the quaternion Q transforms another quaternion P according to P' = Q * P * Q̄, we can also express this rotation in terms of a 4x4 matrix ℳ such that P' = ℳ * P, where P is viewed as a 4-vector in the last line. This function returns that matrix.

Returns

  • m: float array

    Output shape is self.shape[:-1]+(4,4). This matrix should multiply (from the left) a column vector to produce the transformed column vector.

to_vector_part

to_vector_part

Source: quaternionic/converters.py

The "vector" part of the quaternion (final three components). Note that it is entirely standard to describe this part of the quaternion as the "vector" part. It would be more correct to refer to it as the "bivector" part, as explained by geometric algebra.

two_spinor

two_spinor

Source: quaternionic/properties.py

Return the two-spinor representation of the quaternion The standard mapping from quaternions to two-spinors is q ↦ (q.w + 1j * q.z, q.y + 1j * q.x) This function returns a namedtuple with those components (as numpy arrays), where the elements names are 'a' and 'b', respectively.

vector

vector

Source: quaternionic/properties.py

The "vector" part of the quaternion (final three components). Note that it is entirely standard to describe this part of the quaternion as the "vector" part. It would be more correct to refer to it as the "bivector" part, as explained by geometric algebra.

w

w

Source: quaternionic/properties.py

The first (scalar) component of the quaternion

x

x

Source: quaternionic/properties.py

The second component of the quaternion (rotation about x)

y

y

Source: quaternionic/properties.py

The third component of the quaternion (rotation about y)

z

z

Source: quaternionic/properties.py

The fourth component of the quaternion (rotation about z)

QuaternionicArray

QuaternionicArray(jit=functools.partial(<function njit at 0x7f73573632e0>, cache=True), dtype=<class 'float'>)

Source: quaternionic/arrays.py

Construct a quaternionic array type. This factory returns a class encapsulating a quaternionic array type, where the jit function and dtype are passed to this factory function, and used when creating the class. The returned class can then be used to instantiate actual arrays. This allows us to, for example, skip jit compilation and construct numpy arrays of dtype object, so that we can use more general python types than the standard numeric types — such as sympy expressions.