emmy.quaternion — org.mentat/emmy 0.32.0

This namespace provides a number of functions and constructors for working with [[Quaternion]] instances in Clojure and ClojureScript, and installs [[Quaternion]] into the Emmy generic arithmetic system.

For other numeric extensions, see emmy.ratio, emmy.complex and [[emmy.numbers]].

*angle-axis-tolerance* clj/s

Tolerance setting for ->angle-axis.

->4x4-matrix clj/s

(->4x4-matrix q)

Returns the 4x4 matrix representation of the supplied [[Quaternion]] q.

->angle-axis clj/s

(->angle-axis q)

Given a unit quaternion q representing a spatial rotation (sometimes called a 'versor'), returns a pair of

• theta, the rotation in radians about the rotation axis
• axis, a 3-element unit vector with elements x, y and z representing an axis of rotation in 3d Euclidean space.

If the unit quaternion q represents NO rotation, the axis is undefined; this manifests as the squared norm of the non-real vector part of q sitting within *angle-axis-tolerance* of 0.

In this case, the conversion is degenerate and ->angle-axis returns the pair [0 [1 0 0]] as a default. (This check only occurs with a quaternion with all numeric elements in the non-real positions.)

->complex-matrix clj/s

(->complex-matrix q)

Returns a 2x2 complex matrix representation of the supplied Quaternion q.

For a quaternion with coefficients [a b c d], the returned matrix will have the following form:

[ a + b i,  c + d i]
[ -c + d i, a - b i]

NOTE that this currently only works for quaternions q with real or symbolic entries.

->complex-pair clj/s

(->complex-pair q)

Returns a pair of complex number created respectively from the (r,i) and (j,k) components of the supplied quaternion q.

NOTE that this only works if the coefficients of q are real numbers, due to restrictions on the current complex number implementation.

->rotation-matrix clj/s

(->rotation-matrix q)

Given a normalized [[Quaternion]] q, returns the corresponding orthogonal 3x3 rotation matrix representing a rotation in 3d-space.

The implementation here will first normalize q for you and then generate a rotation matrix from that new quaternion q-normal.

->rotation-matrix will still work if q isn't normalized; but if a [[Quaternion]] isn't normalized it doesn't make sense to interpret it as a rotation.

See https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation#Quaternion-derived_rotation_matrix

->vector clj/s

(->vector q)

Returns a 4-vector of the coefficients of quaternion q.

Works identically to (vec q), but more efficient as we are able to create the new vector in one shot.

add clj/s

(add)

(add q)

(add q1 q2)

(add q1 q2 & more)

Variadic function that returns the sum of all supplied quaternions.

Given 1 argument q, acts as identity. Given no arguments, returns ZERO, the additive identity.

The sum of two or more quaternions is a new quaternion with coefficients equal to the elementwise sum of the coefficients of all supplied quaternions.

arity clj/s

(arity q)

Given a quaternion q with function coefficients, returns an arity compatible with all function coefficient entries.

NOTE that by default, if any arities are incompatible, the function will return [:at-least 0]. To force strict arity checks, bind emmy.function/*strict-arity-checks* to true.

commutator clj/s

(commutator l r)

Returns the commutator of the supplied quaternions l and r.

The commutator of two quaternions is equal to

(- (* l r) (* r l))

complex-1 clj/s

(complex-1 q)

Returns the r and i components of the quaternion q as a Complex number instance.

complex-2 clj/s

(complex-2 q)

Returns the j and k components of the quaternion q as a Complex number instance.

conjugate clj/s

(conjugate q)

Returns the conjugate of the supplied quaternion q.

The conjugate of a quaternion is a new quaternion with real coefficient equal to that of q and each imaginary coefficient negated. (mul q (conjugate q)) will return a real? quaternion.

cos clj/s

(cos q)

Returns the cosine of the supplied quaternion q.

See the Boost documentation and source for a reference implementation.

cosh clj/s

(cosh q)

Returns the hyperbolic cosine of the supplied quaternion q.

cosh is defined in terms of the exp function as (e^q + e^{-q}) / 2.

cross-product clj/s

(cross-product l r)

Returns a quaternion representing the (vector) cross product of the two pure sides (retrieved via three-vector) of the supplied quaternions l and r.

NOTE that the suggestion for this function comes from this C++ quaternion library. Strictly, this is not the 'cross product of two quaternions'.

cylindrical clj/s

(cylindrical mag angle j k)

Returns a [[Quaternion]] q with complex-1 built from the polar coordinates mag and angle, and j and k components equal to the supplied j and k.

cylindrospherical clj/s

(cylindrospherical t r theta phi)

Returns a [[Quaternion]] q with real-part equal to t and the three-vector part built from the spherical coordinates r, colat and lon.

div clj/s

(div)

(div q)

(div q1 q2)

(div q1 q2 & more)

Variadic function for dividing quaternion arguments.

• Given no arguments, returns ONE, the multiplicative identity.
• Given 1 argument q, acts as identity.
• Given 2 arguments, returns the quotient of quaternions q1 and q2.
• Given more than 2 arguments, returns the quotient of the first quaternion q1 with the product of all remaining arguments.

The quotient of two quaternions is a new quaternion equal to the product of q1 and the multiplicative inverse of q2

dot-product clj/s

(dot-product l r)

Returns the quaternion dot product of the supplied quaternions l and r.

The quaternion dot product is the sum of the products of the corresponding coefficients of each quaternion, equal to

$$r_l * r_r + i_l * i_r + j_l * j_r + k_l * k_r$$

eq clj/s

(eq q1 q2)

Returns true if the supplied quaternion q1 is equal to the value q2. The rules for eq are as follows:

• If q2 is a quaternion, returns true if all coefficients match, false otherwise

• If q2 is complex, returns true if the real and i coefficients are equal, with j and k coefficients of q1 equal to zero, false otherwise

• If q2 is sequential with a count of 4, it's interpreted as a vector of quaternion coefficients.

Else, if q1 is a real? quaternion, returns true if the real component of q1 is emmy.value/= to q2, false otherwise.

evaluate clj/s

(evaluate q args)

Given a quaternion q with function coefficients and a sequence args of arguments, and returns a new [[Quaternion]] generated by replacing each coefficient with the result of applying the (functional) coefficient to args.

exp clj/s

(exp q)

Returns the exponential $e^q$ of the supplied quaternion q.

Given a quaternion $q$ with real part $r$ and non-real vector $\vec{v}$, the exponential is computed as

$$ \exp(q) = e^r \left(\cos |\mathbf{v}| \

• \frac{\mathbf{v}}{|\mathbf{v}|} \sin|\mathbf{v}| \right) $$

expt clj/s

(expt q p)

Returns the result of raising quaternion q to the real, complex or quaternion power p.

from-4x4-matrix clj/s

(from-4x4-matrix four-matrix)

Given a 4x4 matrix representation of a quaternion, returns the associated quaternion by extracting the first row.

from-angle-axis clj/s

(from-angle-axis angle axis)

Returns a [[Quaternion]] that represents a rotation of angle radians around a normalized version of the vector described by axis. axis must be a 3-vector with components x, y and z.

Given an axis with numeric entries, from-angle-axis will explicitly normalize axis before calling from-angle-normal-axis. If any entries are non-numerical (i.e., symbolic), from-angle-axis will instead log an assumption that the magnitude of axis == 1 and proceed.

NOTE: If you have an already-normalized axis, prefer from-angle-normal-axis.

from-angle-normal-axis clj/s

(from-angle-normal-axis angle [x y z])

Returns a [[Quaternion]] that represents a rotation of angle radians around the unit (normalized) vector described by the second argument, a 3-vector with components x, y and z.

The second argument represents an axis of rotation.

NOTE: If you have an UN-normalized axis, prefer from-angle-axis.

from-complex clj/s

(from-complex a b)

Given two complex numbers a and b, returns a quaternion instance with

• r and i components set to the real and imaginary components of a
• j and k components set to the real and imaginary components of b

from-complex-matrix clj/s

(from-complex-matrix M)

Given a 2x2 complex matrix M of the form

[ a + b i,  c + d i]
[ -c + d i, a - b i]

Returns a [[Quaternion]] instance with coefficients [a b c d].

from-rotation-matrix clj/s

(from-rotation-matrix M)

Given an orthogonal 3x3 matrix M representing a rotation in 3-space, returns the unit quaternion that corresponds to the same transformation.

GJS notes in scmutils that this algorithm is the 'expanded Matt Mason method'.

NOTE Orthogonal means, no stretching allowed, only rotation!

NOTE this routine uses non-generic [[clojure.core/>=]] and [[clojure.core/max]] internally, so if you use numeric entries (or if your entries simplify down to numbers), make sure that they work with these native operations. No BigInt in ClojureScript for now, for example.

get-i clj/s

(get-i q)

Returns the i component of the supplied quaternion q.

get-j clj/s

(get-j q)

Returns the j component of the supplied quaternion q.

get-k clj/s

(get-k q)

Returns the k component of the supplied quaternion q.

get-r clj/s

(get-r q)

Returns the r component of the supplied quaternion q.

Identical to real-part.

I clj/s

Unit quaternion with i coefficient equal to 1, all other coefficients equal to 0.

I-matrix clj/s

4x4 matrix representation of the quaternion I.

I-tensor clj/s

4x4 down-up tensor representation of the quaternion I.

invert clj/s

(invert q)

Returns the multiplicative inverse of the supplied quaternion q.

The inverse of a quaternion is a new quaternion that, when multiplied by q, will produce the ONE quaternion (the multiplicative identity).

J clj/s

Unit quaternion with j coefficient equal to 1, all other coefficients equal to 0.

J-matrix clj/s

4x4 matrix representation of the quaternion J.

J-tensor clj/s

4x4 down-up tensor representation of the quaternion J.

K clj/s

Unit quaternion with k coefficient equal to 1, all other coefficients equal to 0.

K-matrix clj/s

4x4 matrix representation of the quaternion K.

K-tensor clj/s

4x4 down-up tensor representation of the quaternion K.

log clj/s

(log q)

Returns the logarithm $\ln q$ of the supplied quaternion q.

Given a quaternion $q$ with real part $r$ and non-real vector $\vec{v}$, the logarithm is computed as

$$ \ln(q) = \ln |q| + \frac{\mathbf{v}}{|\mathbf{v}|}
\arccos \frac{r}{|\q|} $$

magnitude clj/s

(magnitude q)

Returns the norm of the supplied quaternion q.

The norm of a quaternion is the square root of the sum of the squares of the quaternion's coefficients.

magnitude-sq clj/s

(magnitude-sq q)

Returns the square of the magnitude of the supplied quaternion q, equivalent to taking the dot-product of q with itself.

make clj/s

(make x)

(make r [i j k])

(make r i j k)

Constructor that builds [[Quaternion]] instances out of a variety of types. Given:

• a quaternion x, acts as identity.

• a sequential x, returns a quaternion with coefficients built from the first four entries.

• a complex number x, returns a quaternion built from the real and imaginary components of x with j and k components equal to zero.

• a real number x and 3-vector, returns a quaternion with real coefficient equal to x and imaginary components equal to the elements of the vector

• 4 distinct arguments r, i, j and k, returns a quaternion with these as the coefficients.

mul clj/s

(mul)

(mul q)

(mul q1 q2)

(mul q1 q2 & more)

Variadic function that returns the product of all supplied quaternions.

Given 1 argument q, acts as identity. Given no arguments, returns ONE, the multiplicative identity.

The product of two or more quaternions is a new quaternion generated by multiplying together each quaternion of the form (r+ai+bj+ck), respecting the quaternion rules:

i^2 == j^2 == k^2 == -1 ijk == -1, ij == k, jk == i, ki == j ji == -k, kj == -i, ik == -j

multipolar clj/s

(multipolar r1 theta1 r2 theta2)

Returns a [[Quaternion]] instance with complex-1 part built from the polar coordinates r1 and theta1 and complex-2 part built from r2 and theta2

negate clj/s

(negate q)

Returns the negation (additive inverse) of the supplied quaternion q.

The additive inverse of a quaternion is a new quaternion that, when added to q, will produce the ZERO quaternion (the additive identity).

normalize clj/s

(normalize q)

Returns a new quaternion generated by dividing each coefficient of the supplied quaternion q by the magnitude of q. (If the magnitude is [[zero?]], returns the zero quaternion q.)

The returned quaternion will have magnitude (approximately) equal to

1. unit? will return true for a normalized quaternion, though you may need to supply an :epsilon.

ONE clj/s

The identity quaternion. The real coefficient is equal to 1, and all coefficients are equal to 0.

ONE-matrix clj/s

4x4 matrix representation of the quaternion ONE.

ONE-tensor clj/s

4x4 down-up tensor representation of the quaternion ONE.

partial-derivative clj/s

(partial-derivative q selectors)

Given a quaternion q with function coefficients and a possibly-empty sequence of partial derivative selectors, returns a new [[Quaternion]] generated by replacing each (functional) coefficient with its derivative with respect to selectors.

pitch clj/s

(pitch angle)

Create a quaternion representing a pitch rotation by the supplied angle (specified in radians).

pure? clj/s

(pure? q)

Returns true if the quaternion q has a zero real entry, false otherwise.

A 'pure' quaternion is sometimes called an 'imaginary' quaternion.

q-div-scalar clj/s

(q-div-scalar q s)

Returns a new quaternion generated by dividing each coefficient of the supplied quaternion q by the supplied scalar s.

quaternion? clj/s

(quaternion? q)

Returns true if q is an instance of [[Quaternion]], false otherwise.

real-part clj/s

(real-part q)

Returns the r component of the supplied quaternion q.

Identical to get-r.

real? clj/s

(real? q)

Returns true if the quaternion q has zero entries for all non-real fields, false otherwise.

roll clj/s

(roll angle)

Create a quaternion representing a roll rotation by the supplied angle (specified in radians).

scale clj/s

(scale q s)

Returns a new quaternion generated by multiplying each coefficient of the supplied quaternion q by the supplied scalar s on the right.

scale-l clj/s

(scale-l s q)

Returns a new quaternion generated by multiplying each coefficient of the supplied quaternion q by the supplied scalar s on the left.

semipolar clj/s

(semipolar r alpha theta1 theta2)

Returns a [[Quaternion]] q with magnitude rho, built such that:

• the magnitude of q equals rho
• the magnitude ([[complex-1]] q) equals (* rho (cos alpha))
• the angle of ([[complex-1]] q) equals theta1
• The magnitude ([[complex-2]] q) equals (* rho (cos alpha))
• the angle of ([[complex-2]] q) equals theta12

This strange, possibly unnecessary constructor taken from the Boost quaternion implementation.

sin clj/s

(sin q)

Returns the sine of the supplied quaternion q.

See the Boost documentation and source for a reference implementation.

sinh clj/s

(sinh q)

Returns the hyperbolic sine of the supplied quaternion q.

sinh is defined in terms of the exp function as (e^q - e^{-q}) / 2.

spherical clj/s

(spherical r theta colat lon)

Generates a [[Quaternion]] instance, given:

• a magnitude r
• a rotation angle theta, with a natural range of -2*pi to 2*pi
• colat, the colatitude of the (non-real) vectorial part of the quaternion
• lon, the longitude of the vectorial part of the quaternion

sqrt clj/s

(sqrt q)

Returns the square root of the supplied quaternion q.

([[sqrt]] q) is identical to, but more efficient than, raising q to the 1/2 power.

Thanks to the Spire library for the correct implementation used here.

sub clj/s

(sub)

(sub q)

(sub q1 q2)

(sub q1 q2 & more)

Variadic function for subtracting quaternion arguments.

• Given no arguments, returns ZERO, the additive identity.
• Given 1 argument q, acts as identity.
• Given 2 arguments, returns the difference of quaternions q1 and q2.
• Given more than 2 arguments, returns the difference of the first quaternion q1 with the sum of all remaining arguments.

The difference of two quaternions is a new quaternion with coefficients equal to the pairwise difference of the coefficients of q1 and q2.

tan clj/s

(tan q)

Returns the tangent of the supplied quaternion q.

tan is defined as (/ (sin q) (cos q)).

tanh clj/s

(tanh q)

Returns the hyperbolic tangent of the supplied quaternion q.

tan is defined as (/ (sinh q) (cosh q)).

three-vector clj/s

(three-vector q)

Returns a 3-vector holding the coefficients of the non-real (imaginary) components of the quaternion q.

unit? clj/s

(unit? q & {:keys [epsilon]})

Returns true if q is a unit quaternion (i.e., a 'versor', a quaternion with magnitude equal to one), false otherwise.

To check if the magnitude of q is /approximately/ equal to one, pass a tolerance via the :epsilon keyword argument.

For more control, use magnitude to compute the magnitude directly.

yaw clj/s

(yaw angle)

Create a quaternion representing a yaw rotation by the supplied angle (specified in radians).

ZERO clj/s

The zero quaternion. All coefficients are equal to 0.