quatorch 0.1.0a1

Quaternion operations in pure PyTorch

Quaternions in PyTorch

QuaTorch

The package quatorch provides Quaternion, a torch.Tensor subclass that represents a Quaternion. It implements common operations in following quaternion algebra such as multiplication, conjugation, inversion, normalization, log, exp, etc. It also supports conversion to/from rotation matrix and axis-angle representation. Convenient utilities are provided together, such as spherical linear interpolation (slerp) and 3D vector rotation.

Highlights

• Quaternion type: quatorch.Quaternion (subclass of torch.Tensor).
• Element-wise and algebraic ops implemented: +, -, * (quaternion product and scalar mul), abs (norm), conjugate, inverse, normalize, to_rotation_matrix, and more.
• Utilities: from_rotation_matrix, from_axis_angle, to_axis_angle, rotate_vector, slerp, log, exp, and pow.

Installation

This project targets Python 3.10+ and requires PyTorch. Install via pip (recommended):

pip install quatorch

Or install editable/development mode:

git clone 
cd QuaTorch
pip install -e .

See pyproject.toml for dependency details (dev deps include pytest).

Quick start

Basic usage examples using PyTorch tensors and Quaternion:

import torch
from quatorch.quaternion import Quaternion

# Create a quaternion from four scalars (W, X, Y, Z)
q = Quaternion(1.0, 0.0, 0.0, 0.0)

# Or from a tensor of shape (..., 4)
q2 = Quaternion(torch.tensor([0.9239, 0.3827, 0.0, 0.0]))  # 45° around X

# Normalize
q2 = q2.normalize()

# Quaternion multiplication (rotation composition)
q3 = q * q2

# Rotate a vector
v = torch.tensor([1.0, 0.0, 0.0])
v_rot = q2.rotate_vector(v)

# Convert to rotation matrix
R = q2.to_rotation_matrix()

# Slerp between quaternions
t = 0.5
q_mid = q.slerp(q2, t)

API notes

• Construction:

  • Quaternion(data: torch.Tensor) where data.shape[-1] == 4.
  • Quaternion(w, x, y, z) accepts scalars or tensors broadcastable to the same shape.

• Shape requirements:

  • The last dimension must be size 4 for quaternion tensors (W, X, Y, Z).

• Interoperability:

  • The class implements several torch.* functions via a small dispatcher so many PyTorch APIs behave sensibly with Quaternion objects.

See the source in src/quatorch/quaternion.py for the full implementation and more helper methods.

Running tests

This repository includes unit tests using pytest under test/unit_tests.

From the project root, run:

uv run --with=. pytest 

Contributing

Contributions are welcome. A few ideas:

• Add more conversions and higher-level utilities (e.g., batch rotation helpers).
• Improve numeric stability and add property-based tests.
• Add docs and usage notebooks / examples.

Please open issues or pull requests on the repository.

License

MIT — see the LICENSE.md for author/maintainer information.

Contact

Maintainer: Lucas N. Egidio [e-mail]