Quaternion Class

class fastquat.quaternion.Quaternion(w: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray = 0, x: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray = 0, y: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray = 0, z: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray = 0, dtype: str | type[Any] | dtype | SupportsDType | None = None)

Bases: object

Class for manipulating quaternion tensors with JAX.

A quaternion is represented by [w, x, y, z] where w is the scalar part and (x, y, z) is the vector part.

__init__(w: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray = 0, x: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray = 0, y: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray = 0, z: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray = 0, dtype: str | type[Any] | dtype | SupportsDType | None = None) → None

Initialize a tensor of quaternions.

Parameters:

• w – components of the quaternions.

• x – components of the quaternions.

• y – components of the quaternions.

• z – components of the quaternions.

• dtype – Data type of the quaternion components (inferred by default).

tree_flatten() → tuple[tuple[Any, ...], Any]

Flatten the Quaternion PyTree.

classmethod tree_unflatten(aux_data, children) → Self

Unflatten The Quaternion PyTree

classmethod from_array(array: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray) → Self

Create a Quaternion array from a numeric array of shape (…, 4).

Parameters:

array – array of shape (…, 4) where the last dimension is [w, x, y, z]

classmethod from_scalar_vector(scalar: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray, vector: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray) → Self

Create a quaternion from scalar and vector parts.

Parameters:

• scalar – Array of shape (…,) for the scalar part.

• vector – Array of shape (…, 3) for the vector part.

Returns:

Quaternion

classmethod from_rotation_matrix(rot: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray) → Self

Create the quaternion associated to a rotation matrix.

Parameters:

rot – Array of shape (…, 3, 3) representing the rotation matrix

Returns:

The normalized Quaternion tensor representing the rotation matrix.

classmethod zeros(shape: tuple[int, ...], dtype: str | type[Any] | dtype | SupportsDType | None = None) → Self

Create quaternions with all components set to 0.

Parameters:

• shape – Shape of the tensor (without the last dimension).

• dtype – Data type of the quaternion components.

Returns:

Quaternion with all components equal to 0.

classmethod ones(shape: tuple[int, ...], dtype: str | type[Any] | dtype | SupportsDType | None = None) → Self

Create quaternions with scalar component set to 1 and vector components set to 0.

Parameters:

• shape – Shape of the tensor (without the last dimension).

• dtype – Data type of the quaternion components.

Returns:

Quaternions with w=1 and x=y=z=0.

classmethod full(shape: tuple[int, ...], fill_value: float, dtype: str | type[Any] | dtype | SupportsDType | None = None) → Self

Create quaternions with scalar component set to a value and vector components set to 0.

Parameters:

• shape – Shape of the tensor (without the last dimension).

• fill_value – Value to fill the scalar component with.

• dtype – Data type of the quaternion components.

Returns:

Quaternions with w=fill_value and x=y=z=0.

classmethod random(key: PRNGKey, shape: tuple[int, ...] = (), dtype: str | type[Any] | dtype | SupportsDType | None = None) → Self

Generate normalized random quaternions.

Parameters:

• key – Key PRNG.

• shape – Shape of the tensor (without the last dimension).

• dtype – Data type of the quaternion components.

Returns:

Normalized Quaternion.

property w: Array

property x: Array

property y: Array

property z: Array

property vector: Array

Vector part (…, 3)

__abs__() → Array

Quaternion norm.

normalize() → Self

Normalize the quaternion.

Returns the normalized quaternion. If the quaternion has zero norm, returns the quaternion [NaN, NaN, NaN, NaN].

to_components() → tuple[Array, Array, Array, Array]

to_rotation_matrix() → Array

Convert quaternion to rotation matrix.

Returns:

Array of shape (…, 3, 3)

rotate_vector(v: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray) → Array

Apply quaternion rotation to a vector.

Parameters:

v – Array of shape (…, 3) representing vectors

Returns:

Array of shape (…, 3) representing rotated vectors

__len__()

Length of the first axis.

__iter__()

Iterate over the first axis.

__pos__() → Self

Quaternion positive.

__neg__() → Self

Quaternion negation.

__add__(other: Any) → Self

Quaternion addition.

__radd__(other: Any) → Self

Quaternion addition.

__sub__(other: Any) → Self

Quaternion subtraction.

__rsub__(other: Any) → Self

Quaternion subtraction.

__mul__(other: Any) → Self

Quaternion multiplication.

__rmul__(other: Any) → Self

Quaternion multiplication.

__truediv__(other: Any) → Self

Quaternion division.

__rtruediv__(other: Any) → Self

Quaternion division.

__pow__(exponent: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray) → Self

Quaternion exponentiation q^n.

For integer exponents, uses optimized special cases. For non-integer exponents, uses the general formula: q^n = exp(n * log(q))

Parameters:

exponent – The exponent (scalar or array)

Returns:

The quaternion raised to the given power

log() → Self

Compute quaternion logarithm.

For a quaternion q = ‖q‖ * (cos(θ) + sin(θ)v), the logarithm is: log(q) = log(‖q‖) + θ * v

For the zero quaternion, returns (-inf, 0, 0, 0).

Returns:

The logarithm of the quaternion

exp() → Self

Compute quaternion exponential.

For a quaternion q = s + v, the exponential is: exp(q) = exp(s) * (cos(‖v‖) + sin(‖v‖) * v/‖v‖)

Returns:

The exponential of the quaternion

property nbytes: int

Number of bytes in the tensor.

property itemsize: int

Size of one quaternion element in bytes.

property shape: tuple[int, ...]

Shape of the tensor.

property ndim

Number of dimensions of the quaternion tensor (without the quaternion dimension).

property size

Total number of quaternions.

property dtype: dtype

Data type.

reshape(*shape) → Self

Redimensionne le tableau de quaternions

flatten() → Self

Aplatis le tableau de quaternions

ravel() → Self

Aplatis le tableau de quaternions

squeeze(axis=None) → Self

Supprime les dimensions de taille 1

conjugate() → Self

Quaternion conjugate.

conj() → Self

Quaternion conjugate.

block_until_ready() → None

Block until all pending computations are done.

property device: Device

devices() → set[Device]

slerp(other: Self, t: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray) → Self

Spherical linear interpolation between two quaternions.

Parameters:

• other – Target quaternion to interpolate towards

• t – Interpolation parameter in [0, 1]. t=0 returns self, t=1 returns other

Returns:

Interpolated quaternion

The Quaternion class provides a comprehensive interface for quaternion operations optimized for JAX. All methods are compatible with JAX transformations including JIT compilation, automatic differentiation, and vectorization.

Constructor Methods

Quaternion.__init__(w: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray = 0, x: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray = 0, y: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray = 0, z: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray = 0, dtype: str | type[Any] | dtype | SupportsDType | None = None) → None

Initialize a tensor of quaternions.

Parameters:

• w – components of the quaternions.

• x – components of the quaternions.

• y – components of the quaternions.

• z – components of the quaternions.

• dtype – Data type of the quaternion components (inferred by default).

classmethod Quaternion.from_array(array: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray) → Self

Create a Quaternion array from a numeric array of shape (…, 4).

Parameters:

array – array of shape (…, 4) where the last dimension is [w, x, y, z]

classmethod Quaternion.from_scalar_vector(scalar: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray, vector: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray) → Self

Create a quaternion from scalar and vector parts.

Parameters:

• scalar – Array of shape (…,) for the scalar part.

• vector – Array of shape (…, 3) for the vector part.

Returns:

Quaternion

classmethod Quaternion.from_rotation_matrix(rot: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray) → Self

Create the quaternion associated to a rotation matrix.

Parameters:

rot – Array of shape (…, 3, 3) representing the rotation matrix

Returns:

The normalized Quaternion tensor representing the rotation matrix.

classmethod Quaternion.zeros(shape: tuple[int, ...], dtype: str | type[Any] | dtype | SupportsDType | None = None) → Self

Create quaternions with all components set to 0.

Parameters:

• shape – Shape of the tensor (without the last dimension).

• dtype – Data type of the quaternion components.

Returns:

Quaternion with all components equal to 0.

classmethod Quaternion.ones(shape: tuple[int, ...], dtype: str | type[Any] | dtype | SupportsDType | None = None) → Self

Create quaternions with scalar component set to 1 and vector components set to 0.

Parameters:

• shape – Shape of the tensor (without the last dimension).

• dtype – Data type of the quaternion components.

Returns:

Quaternions with w=1 and x=y=z=0.

classmethod Quaternion.full(shape: tuple[int, ...], fill_value: float, dtype: str | type[Any] | dtype | SupportsDType | None = None) → Self

Create quaternions with scalar component set to a value and vector components set to 0.

Parameters:

• shape – Shape of the tensor (without the last dimension).

• fill_value – Value to fill the scalar component with.

• dtype – Data type of the quaternion components.

Returns:

Quaternions with w=fill_value and x=y=z=0.

classmethod Quaternion.random(key: PRNGKey, shape: tuple[int, ...] = (), dtype: str | type[Any] | dtype | SupportsDType | None = None) → Self

Generate normalized random quaternions.

Parameters:

• key – Key PRNG.

• shape – Shape of the tensor (without the last dimension).

• dtype – Data type of the quaternion components.

Returns:

Normalized Quaternion.

Properties

Quaternion.w

Quaternion.x

Quaternion.y

Quaternion.z

Quaternion.vector

Vector part (…, 3)

Quaternion.shape

Shape of the tensor.

Quaternion.dtype

Data type.

Core Operations

Quaternion.__abs__() → Array

Quaternion norm.

Quaternion.normalize() → Self

Normalize the quaternion.

Returns the normalized quaternion. If the quaternion has zero norm, returns the quaternion [NaN, NaN, NaN, NaN].

Quaternion.conjugate() → Self

Quaternion conjugate.

Quaternion.conj() → Self

Quaternion conjugate.

Quaternion.to_components() → tuple[Array, Array, Array, Array]

Rotation Operations

Quaternion.to_rotation_matrix() → Array

Convert quaternion to rotation matrix.

Returns:

Array of shape (…, 3, 3)

Quaternion.rotate_vector(v: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray) → Array

Apply quaternion rotation to a vector.

Parameters:

v – Array of shape (…, 3) representing vectors

Returns:

Array of shape (…, 3) representing rotated vectors

Interpolation

Quaternion.slerp(other: Self, t: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray) → Self

Spherical linear interpolation between two quaternions.

Parameters:

• other – Target quaternion to interpolate towards

• t – Interpolation parameter in [0, 1]. t=0 returns self, t=1 returns other

Returns:

Interpolated quaternion

Advanced Operations

Quaternion.log() → Self

Compute quaternion logarithm.

For a quaternion q = ‖q‖ * (cos(θ) + sin(θ)v), the logarithm is: log(q) = log(‖q‖) + θ * v

For the zero quaternion, returns (-inf, 0, 0, 0).

Returns:

The logarithm of the quaternion

Quaternion.exp() → Self

Compute quaternion exponential.

For a quaternion q = s + v, the exponential is: exp(q) = exp(s) * (cos(‖v‖) + sin(‖v‖) * v/‖v‖)

Returns:

The exponential of the quaternion

Quaternion.__pow__(exponent: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray) → Self

Quaternion exponentiation q^n.

For integer exponents, uses optimized special cases. For non-integer exponents, uses the general formula: q^n = exp(n * log(q))

Parameters:

exponent – The exponent (scalar or array)

Returns:

The quaternion raised to the given power

Array Operations

Quaternion.reshape(*shape) → Self

Redimensionne le tableau de quaternions

Quaternion.flatten() → Self

Aplatis le tableau de quaternions

Quaternion.ravel() → Self

Aplatis le tableau de quaternions

Quaternion.squeeze(axis=None) → Self

Supprime les dimensions de taille 1

Quaternion.block_until_ready() → None

Block until all pending computations are done.

Device and Memory

Quaternion.device

Quaternion.devices() → set[Device]

Quaternion.nbytes

Number of bytes in the tensor.

Quaternion.itemsize

Size of one quaternion element in bytes.

Quaternion.size

Total number of quaternions.

Quaternion.ndim

Number of dimensions of the quaternion tensor (without the quaternion dimension).