jaxdem.utils.quaternion#

Quaternion math utilities.

Classes

Quaternion(w, xyz)

Quaternion representation for 2D and 3D particle orientations.
class jaxdem.utils.quaternion.Quaternion(w: Array, xyz: Array)#

Bases: object

Quaternion representation for 2D and 3D particle orientations.

A quaternion \(q\) is represented as a scalar part \(w\) and a vector part \(\vec{v}_{xyz} = (x, y, z)\):

\[q = w + x\mathbf{i} + y\mathbf{j} + z\mathbf{k}\]

In 2D, the rotation axis is restricted to the z-axis: \(\vec{v}_{xyz} = (0, 0, z)\).

w#

The scalar component of the quaternion. Shape is (…, N, 1).

Type:

jax.Array

xyz#

The vector components of the quaternion. Shape is (…, N, 3).

Type:

jax.Array

w: Array#
xyz: Array#
static create(w: Array | ndarray | bool | number | bool | int | float | complex | None = None, xyz: Array | ndarray | bool | number | bool | int | float | complex | None = None) → Quaternion[source]#

Create a Quaternion instance.

Parameters:

  • w (ArrayLike, optional) – The scalar component. If None, defaults to ones.

  • xyz (ArrayLike, optional) – The vector component. If None, defaults to zeros.

Returns:

The created quaternion.

Return type:

Quaternion

static unit(q: Quaternion) → Quaternion[source]#

Normalize a quaternion to have unit norm.

\[q_{unit} = \frac{q}{\|q\|} = \frac{q}{\sqrt{w^2 + x^2 + y^2 + z^2}}\]
Parameters:

q (Quaternion) – The quaternion to normalize.

Returns:

The normalized unit quaternion.

Return type:

Quaternion

static conj(q: Quaternion) → Quaternion[source]#

Compute the conjugate of a quaternion.

\[q^* = w - x\mathbf{i} - y\mathbf{j} - z\mathbf{k}\]
Parameters:

q (Quaternion) – The quaternion.

Returns:

The conjugate quaternion.

Return type:

Quaternion

static inv(q: Quaternion) → Quaternion[source]#

Compute the inverse of a quaternion.

For a unit quaternion, the inverse is equal to its conjugate:

\[q^{-1} = \frac{q^*}{\|q\|^2}\]
Parameters:

q (Quaternion) – The quaternion.

Returns:

The inverse quaternion.

Return type:

Quaternion

static rotate(q: Quaternion, v: Array) → Array[source]#

Rotates a vector \(\vec{v}\) from the body reference frame to the lab reference frame.

In 3D, the rotation of a vector \(\vec{v}\) by a unit quaternion \(q = (w, \vec{q}_{xyz})\) is:

\[\vec{v}' = \vec{v} + 2 w (\vec{q}_{xyz} \times \vec{v}) + 2 (\vec{q}_{xyz} \times (\vec{q}_{xyz} \times \vec{v}))\]

In 2D, where rotation is restricted to the z-axis, the rotation by angle \(\theta\) (corresponding to quaternion components \(w = \cos(\theta/2)\) and \(q_z = \sin(\theta/2)\)) is:

\[\begin{split}x' &= x \cos(\theta) - y \sin(\theta) \\ y' &= x \sin(\theta) + y \cos(\theta)\end{split}\]
Parameters:

  • q (Quaternion) – The rotation quaternion.

  • v (jax.Array) – The vector to rotate. Shape is (…, dim).

Returns:

The rotated vector in the lab frame. Shape is (…, dim).

Return type:

jax.Array

static rotate_back(q: Quaternion, v: Array) → Array[source]#

Rotates a vector \(\vec{v}\) from the lab reference frame to the body reference frame.

This performs the inverse rotation using the quaternion conjugate \(q^* = (w, -\vec{q}_{xyz})\):

\[\vec{v}' = \vec{v} - 2 w (\vec{q}_{xyz} \times \vec{v}) + 2 (\vec{q}_{xyz} \times (\vec{q}_{xyz} \times \vec{v}))\]
Parameters:

  • q (Quaternion) – The rotation quaternion.

  • v (jax.Array) – The vector to rotate back. Shape is (…, dim).

Returns:

The rotated vector in the body frame. Shape is (…, dim).

Return type:

jax.Array