Algebras

Introduction

The Algebras module for SymPy provides support for basic algebraic operations on Quaternions.

Quaternion Reference

This section lists the classes implemented by the Algebras module.

class sympy.algebras.Quaternion(a=0, b=0, c=0, d=0, real_field=True)

Provides basic quaternion operations. Quaternion objects can be instantiated as Quaternion(a, b, c, d) as in (a + b*i + c*j + d*k).

Examples

>>> from sympy import Quaternion
>>> q = Quaternion(1, 2, 3, 4)
>>> q
1 + 2*i + 3*j + 4*k

Quaternions over complex fields can be defined as :

>>> from sympy import Quaternion
>>> from sympy import symbols, I
>>> x = symbols('x')
>>> q1 = Quaternion(x, x**3, x, x**2, real_field = False)
>>> q2 = Quaternion(3 + 4*I, 2 + 5*I, 0, 7 + 8*I, real_field = False)
>>> q1
x + x**3*i + x*j + x**2*k
>>> q2
(3 + 4*I) + (2 + 5*I)*i + 0*j + (7 + 8*I)*k

References

R1

http://www.euclideanspace.com/maths/algebra/realNormedAlgebra/quaternions/

R2

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

add(other)

Adds quaternions.

Parameters

other : Quaternion

The quaternion to add to current (self) quaternion.

Returns

Quaternion

The resultant quaternion after adding self to other

Examples

>>> from sympy import Quaternion
>>> from sympy import symbols
>>> q1 = Quaternion(1, 2, 3, 4)
>>> q2 = Quaternion(5, 6, 7, 8)
>>> q1.add(q2)
6 + 8*i + 10*j + 12*k
>>> q1 + 5
6 + 2*i + 3*j + 4*k
>>> x = symbols('x', real = True)
>>> q1.add(x)
(x + 1) + 2*i + 3*j + 4*k

Quaternions over complex fields :

>>> from sympy import Quaternion
>>> from sympy import I
>>> q3 = Quaternion(3 + 4*I, 2 + 5*I, 0, 7 + 8*I, real_field = False)
>>> q3.add(2 + 3*I)
(5 + 7*I) + (2 + 5*I)*i + 0*j + (7 + 8*I)*k

angle()

Returns the angle of the quaternion measured in the real-axis plane.

Explanation

Given a quaternion \(q = a + bi + cj + dk\) where a, b, c and d are real numbers, returns the angle of the quaternion given by

\[angle := atan2(\sqrt{b^2 + c^2 + d^2}, {a})\]

Examples

>>> from sympy.algebras.quaternion import Quaternion
>>> q = Quaternion(1, 4, 4, 4)
>>> q.angle()
atan(4*sqrt(3))

arc_coplanar(other)

Returns True if the transformation arcs represented by the input quaternions happen in the same plane.

Parameters

other : a Quaternion

Returns

True : if the planes of the two quaternions are the same, apart from its orientation/sign.

False : if the planes of the two quaternions are not the same, apart from its orientation/sign.

None : if plane of either of the quaternion is unknown.

Explanation

Two quaternions are said to be coplanar (in this arc sense) when their axes are parallel. The plane of a quaternion is the one normal to its axis.

Examples

>>> from sympy.algebras.quaternion import Quaternion
>>> q1 = Quaternion(1, 4, 4, 4)
>>> q2 = Quaternion(3, 8, 8, 8)
>>> Quaternion.arc_coplanar(q1, q2)
True

>>> q1 = Quaternion(2, 8, 13, 12)
>>> Quaternion.arc_coplanar(q1, q2)
False

See also

vector_coplanar, is_pure

axis()

Returns the axis(\(\mathbf{Ax}(q)\)) of the quaternion.

Explanation

Given a quaternion \(q = a + bi + cj + dk\), returns \(\mathbf{Ax}(q)\) i.e., the versor of the vector part of that quaternion equal to \(\mathbf{U}[\mathbf{V}(q)]\). The axis is always an imaginary unit with square equal to \(-1 + 0i + 0j + 0k\).

Examples

>>> from sympy.algebras.quaternion import Quaternion
>>> q = Quaternion(1, 1, 1, 1)
>>> q.axis()
0 + sqrt(3)/3*i + sqrt(3)/3*j + sqrt(3)/3*k

See also

vector_part

exp()

Returns the exponential of q (e^q).

Returns

Quaternion

Exponential of q (e^q).

Examples

>>> from sympy import Quaternion
>>> q = Quaternion(1, 2, 3, 4)
>>> q.exp()
E*cos(sqrt(29))
+ 2*sqrt(29)*E*sin(sqrt(29))/29*i
+ 3*sqrt(29)*E*sin(sqrt(29))/29*j
+ 4*sqrt(29)*E*sin(sqrt(29))/29*k

classmethod from_axis_angle(vector, angle)

Returns a rotation quaternion given the axis and the angle of rotation.

Parameters

vector : tuple of three numbers

The vector representation of the given axis.

angle : number

The angle by which axis is rotated (in radians).

Returns

Quaternion

The normalized rotation quaternion calculated from the given axis and the angle of rotation.

Examples

>>> from sympy import Quaternion
>>> from sympy import pi, sqrt
>>> q = Quaternion.from_axis_angle((sqrt(3)/3, sqrt(3)/3, sqrt(3)/3), 2*pi/3)
>>> q
1/2 + 1/2*i + 1/2*j + 1/2*k

classmethod from_rotation_matrix(M)

Returns the equivalent quaternion of a matrix. The quaternion will be normalized only if the matrix is special orthogonal (orthogonal and det(M) = 1).

Parameters

M : Matrix

Input matrix to be converted to equivalent quaternion. M must be special orthogonal (orthogonal and det(M) = 1) for the quaternion to be normalized.

Returns

Quaternion

The quaternion equivalent to given matrix.

Examples

>>> from sympy import Quaternion
>>> from sympy import Matrix, symbols, cos, sin, trigsimp
>>> x = symbols('x')
>>> M = Matrix([[cos(x), -sin(x), 0], [sin(x), cos(x), 0], [0, 0, 1]])
>>> q = trigsimp(Quaternion.from_rotation_matrix(M))
>>> q
sqrt(2)*sqrt(cos(x) + 1)/2 + 0*i + 0*j + sqrt(2 - 2*cos(x))*sign(sin(x))/2*k

index_vector()

Returns the index vector of the quaternion.

Returns

Quaternion: representing index vector of the provided quaternion.

Explanation

Index vector is given by \(\mathbf{T}(q)\) multiplied by \(\mathbf{Ax}(q)\) where \(\mathbf{Ax}(q)\) is the axis of the quaternion q, and mod(q) is the \(\mathbf{T}(q)\) (magnitude) of the quaternion.

Examples

>>> from sympy.algebras.quaternion import Quaternion
>>> q = Quaternion(2, 4, 2, 4)
>>> q.index_vector()
0 + 4*sqrt(10)/3*i + 2*sqrt(10)/3*j + 4*sqrt(10)/3*k

See also

axis, norm

integrate(*args)

Computes integration of quaternion.

Returns

Quaternion

Integration of the quaternion(self) with the given variable.

Examples

Indefinite Integral of quaternion :

>>> from sympy import Quaternion
>>> from sympy.abc import x
>>> q = Quaternion(1, 2, 3, 4)
>>> q.integrate(x)
x + 2*x*i + 3*x*j + 4*x*k

Definite integral of quaternion :

>>> from sympy import Quaternion
>>> from sympy.abc import x
>>> q = Quaternion(1, 2, 3, 4)
>>> q.integrate((x, 1, 5))
4 + 8*i + 12*j + 16*k

inverse()

Returns the inverse of the quaternion.

is_pure()

Returns true if the quaternion is pure, false if the quaternion is not pure or returns none if it is unknown.

Explanation

A pure quaternion (also a vector quaternion) is a quaternion with scalar part equal to 0.

Examples

>>> from sympy.algebras.quaternion import Quaternion
>>> q = Quaternion(0, 8, 13, 12)
>>> q.is_pure()
True

See also

scalar_part

is_zero_quaternion()

Returns true if the quaternion is a zero quaternion or false if it is not a zero quaternion and None if the value is unknown.

Explanation

A zero quaternion is a quaternion with both scalar part and vector part equal to 0.

Examples

>>> from sympy.algebras.quaternion import Quaternion
>>> q = Quaternion(1, 0, 0, 0)
>>> q.is_zero_quaternion()
False

>>> q = Quaternion(0, 0, 0, 0)
>>> q.is_zero_quaternion()
True

See also

scalar_part, vector_part

mensor()

Returns the natural logarithm of the norm(magnitude) of the quaternion.

Examples

>>> from sympy.algebras.quaternion import Quaternion
>>> q = Quaternion(2, 4, 2, 4)
>>> q.mensor()
log(2*sqrt(10))
>>> q.norm()
2*sqrt(10)

See also

norm

mul(other)

Multiplies quaternions.

Parameters

other : Quaternion or symbol

The quaternion to multiply to current (self) quaternion.

Returns

Quaternion

The resultant quaternion after multiplying self with other

Examples

>>> from sympy import Quaternion
>>> from sympy import symbols
>>> q1 = Quaternion(1, 2, 3, 4)
>>> q2 = Quaternion(5, 6, 7, 8)
>>> q1.mul(q2)
(-60) + 12*i + 30*j + 24*k
>>> q1.mul(2)
2 + 4*i + 6*j + 8*k
>>> x = symbols('x', real = True)
>>> q1.mul(x)
x + 2*x*i + 3*x*j + 4*x*k

Quaternions over complex fields :

>>> from sympy import Quaternion
>>> from sympy import I
>>> q3 = Quaternion(3 + 4*I, 2 + 5*I, 0, 7 + 8*I, real_field = False)
>>> q3.mul(2 + 3*I)
(2 + 3*I)*(3 + 4*I) + (2 + 3*I)*(2 + 5*I)*i + 0*j + (2 + 3*I)*(7 + 8*I)*k

norm()

Returns the norm of the quaternion.

normalize()

Returns the normalized form of the quaternion.

orthogonal(other)

Returns the orthogonality of two quaternions.

Parameters

other : a Quaternion

Returns

True : if the two pure quaternions seen as 3D vectors are orthogonal.

False : if the two pure quaternions seen as 3D vectors are not orthogonal.

None : if the two pure quaternions seen as 3D vectors are orthogonal is unknown.

Explanation

Two pure quaternions are called orthogonal when their product is anti-commutative.

Examples

>>> from sympy.algebras.quaternion import Quaternion
>>> q = Quaternion(0, 4, 4, 4)
>>> q1 = Quaternion(0, 8, 8, 8)
>>> q.orthogonal(q1)
False

>>> q1 = Quaternion(0, 2, 2, 0)
>>> q = Quaternion(0, 2, -2, 0)
>>> q.orthogonal(q1)
True

parallel(other)

Returns True if the two pure quaternions seen as 3D vectors are parallel.

Parameters

other : a Quaternion

Returns

True : if the two pure quaternions seen as 3D vectors are parallel.

False : if the two pure quaternions seen as 3D vectors are not parallel.

None : if the two pure quaternions seen as 3D vectors are parallel is unknown.

Explanation

Two pure quaternions are called parallel when their vector product is commutative which implies that the quaternions seen as 3D vectors have same direction.

Examples

>>> from sympy.algebras.quaternion import Quaternion
>>> q = Quaternion(0, 4, 4, 4)
>>> q1 = Quaternion(0, 8, 8, 8)
>>> q.parallel(q1)
True

>>> q1 = Quaternion(0, 8, 13, 12)
>>> q.parallel(q1)
False

pow(p)

Finds the pth power of the quaternion.

Parameters

p : int

Power to be applied on quaternion.

Returns

Quaternion

Returns the p-th power of the current quaternion. Returns the inverse if p = -1.

Examples

>>> from sympy import Quaternion
>>> q = Quaternion(1, 2, 3, 4)
>>> q.pow(4)
668 + (-224)*i + (-336)*j + (-448)*k

pow_cos_sin(p)

Computes the pth power in the cos-sin form.

Parameters

p : int

Power to be applied on quaternion.

Returns

Quaternion

The p-th power in the cos-sin form.

Examples

>>> from sympy import Quaternion
>>> q = Quaternion(1, 2, 3, 4)
>>> q.pow_cos_sin(4)
900*cos(4*acos(sqrt(30)/30))
+ 1800*sqrt(29)*sin(4*acos(sqrt(30)/30))/29*i
+ 2700*sqrt(29)*sin(4*acos(sqrt(30)/30))/29*j
+ 3600*sqrt(29)*sin(4*acos(sqrt(30)/30))/29*k

static rotate_point(pin, r)

Returns the coordinates of the point pin(a 3 tuple) after rotation.

Parameters

pin : tuple

A 3-element tuple of coordinates of a point which needs to be rotated.

r : Quaternion or tuple

Axis and angle of rotation.

It’s important to note that when r is a tuple, it must be of the form (axis, angle)

Returns

tuple

The coordinates of the point after rotation.

Examples

>>> from sympy import Quaternion
>>> from sympy import symbols, trigsimp, cos, sin
>>> x = symbols('x')
>>> q = Quaternion(cos(x/2), 0, 0, sin(x/2))
>>> trigsimp(Quaternion.rotate_point((1, 1, 1), q))
(sqrt(2)*cos(x + pi/4), sqrt(2)*sin(x + pi/4), 1)
>>> (axis, angle) = q.to_axis_angle()
>>> trigsimp(Quaternion.rotate_point((1, 1, 1), (axis, angle)))
(sqrt(2)*cos(x + pi/4), sqrt(2)*sin(x + pi/4), 1)

scalar_part()

Returns scalar part(\(\mathbf{S}(q)\)) of the quaternion q.

Explanation

Given a quaternion \(q = a + bi + cj + dk\), returns \(\mathbf{S}(q) = a\).

Examples

>>> from sympy.algebras.quaternion import Quaternion
>>> q = Quaternion(4, 8, 13, 12)
>>> q.scalar_part()
4

to_axis_angle()

Returns the axis and angle of rotation of a quaternion

Returns

tuple

Tuple of (axis, angle)

Examples

>>> from sympy import Quaternion
>>> q = Quaternion(1, 1, 1, 1)
>>> (axis, angle) = q.to_axis_angle()
>>> axis
(sqrt(3)/3, sqrt(3)/3, sqrt(3)/3)
>>> angle
2*pi/3

to_rotation_matrix(v=None)

Returns the equivalent rotation transformation matrix of the quaternion which represents rotation about the origin if v is not passed.

Parameters

v : tuple or None

Default value: None

Returns

tuple

Returns the equivalent rotation transformation matrix of the quaternion which represents rotation about the origin if v is not passed.

Examples

>>> from sympy import Quaternion
>>> from sympy import symbols, trigsimp, cos, sin
>>> x = symbols('x')
>>> q = Quaternion(cos(x/2), 0, 0, sin(x/2))
>>> trigsimp(q.to_rotation_matrix((1, 1, 1)))
 Matrix([
[cos(x), -sin(x), 0,  sin(x) - cos(x) + 1],
[sin(x),  cos(x), 0, -sin(x) - cos(x) + 1],
[     0,       0, 1,                    0],
[     0,       0, 0,                    1]])

classmethod vector_coplanar(q1, q2, q3)

Returns True if the axis of the pure quaternions seen as 3D vectors q1, q2, and q3 are coplanar.

Parameters

q1 : a pure Quaternion.

q2 : a pure Quaternion.

q3 : a pure Quaternion.

Returns

True : if the axis of the pure quaternions seen as 3D vectors

q1, q2, and q3 are coplanar.

False : if the axis of the pure quaternions seen as 3D vectors

q1, q2, and q3 are not coplanar.

None : if the axis of the pure quaternions seen as 3D vectors

q1, q2, and q3 are coplanar is unknown.

Explanation

Three pure quaternions are vector coplanar if the quaternions seen as 3D vectors are coplanar.

Examples

>>> from sympy.algebras.quaternion import Quaternion
>>> q1 = Quaternion(0, 4, 4, 4)
>>> q2 = Quaternion(0, 8, 8, 8)
>>> q3 = Quaternion(0, 24, 24, 24)
>>> Quaternion.vector_coplanar(q1, q2, q3)
True

>>> q1 = Quaternion(0, 8, 16, 8)
>>> q2 = Quaternion(0, 8, 3, 12)
>>> Quaternion.vector_coplanar(q1, q2, q3)
False

See also

axis, is_pure

vector_part()

Returns vector part(\(\mathbf{V}(q)\)) of the quaternion q.

Explanation

Given a quaternion \(q = a + bi + cj + dk\), returns \(\mathbf{V}(q) = bi + cj + dk\).

Examples

>>> from sympy.algebras.quaternion import Quaternion
>>> q = Quaternion(1, 1, 1, 1)
>>> q.vector_part()
0 + 1*i + 1*j + 1*k

>>> q = Quaternion(4, 8, 13, 12)
>>> q.vector_part()
0 + 8*i + 13*j + 12*k