FastQuat 0.5.2__tar.gz → 1.0b2__tar.gz

{fastquat-0.5.2 → fastquat-1.0b2}/.github/workflows/ci.yml

@@ -35,7 +35,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.10', '3.11', '3.12', '3.13']
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
 
     steps:
       - name: Checkout code
@@ -58,7 +58,7 @@ jobs:
 
       - name: Install project's wheel and dependencies
         run: |
-          uv sync --group dev --no-install-project
+          uv sync --locked --no-install-project
           uv pip install dist/fastquat-*.whl
 
       - name: Run tests

{fastquat-0.5.2 → fastquat-1.0b2}/.pre-commit-config.yaml

@@ -30,6 +30,13 @@ repos:
   - id: end-of-file-fixer
   - id: check-merge-conflict
 
+- repo: https://github.com/kynan/nbstripout
+  rev: 0.6.1
+  hooks:
+  - id: nbstripout
+    name: notebook stripping
+    args: [--extra-keys=metadata.language_info.version]
+
 - repo: https://github.com/pre-commit/mirrors-mypy
   rev: 'v1.19.0'
   hooks:

{fastquat-0.5.2 → fastquat-1.0b2}/.readthedocs.yaml

@@ -1,10 +1,8 @@
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
-# Required
 version: 2
 
-# Set the OS, Python version, and other tools you might need
 build:
   os: ubuntu-24.04
   tools:
@@ -20,10 +18,6 @@ sphinx:
   configuration: docs/source/conf.py
   fail_on_warning: false
 
-# Optionally build your docs in additional formats such as PDF and ePub
-# formats:
-#   - pdf
-
 # Set the version of Python and other tools you might need
 submodules:
   include: all

{fastquat-0.5.2 → fastquat-1.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: FastQuat
-Version: 0.5.2
+Version: 1.0b2
 Summary: High-performance quaternions with JAX support
 Project-URL: homepage, https://fastquat.readthedocs.io
 Project-URL: repository, https://github.com/CMBSciPol/fastquat
@@ -12,12 +12,13 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Astronomy
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Classifier: Topic :: Scientific/Engineering :: Physics
 Requires-Python: >=3.10
 Requires-Dist: jax>=0.4.0
-Requires-Dist: jaxlib>=0.4.0
+Requires-Dist: typing-extensions; python_version < '3.11'
 Description-Content-Type: text/markdown
 
 # FastQuat - High-Performance Quaternions with JAX
@@ -52,13 +53,28 @@ import jax.numpy as jnp
 from fastquat import Quaternion
 
 # Create quaternions
-q1 = Quaternion.ones()  # Identity quaternion
+q1 = Quaternion(1)  # Identity quaternion
 q2 = Quaternion(0.7071, 0.7071, 0.0, 0.0)  # 90° rotation around x-axis
+q = Quaternion(1.0, 0.1, 0.2, 0.3)
+p = 2
 
-# Quaternion operations
-q3 = q1 * q2  # Multiplication
-q_inv = 1 / q1           # Inverse, or q1 ** -1
-q_norm = q1.normalize()  # Normalization
+# Arithmetic
+q_sum = q1 + q2
+q_diff = q1 - q2
+q_product = q1 * q2
+q_power = q**p
+
+# Normalization
+norm = abs(q)  # Quaternion norm
+q_unit = q.normalize()  # Unit quaternion
+
+# Conjugation and inverse
+q_conj = q.conj()  # Conjugate
+q_inv = 1 / q  # Inverse, or q ** -1
+
+# Other operations
+q_log = q.log()
+q_exp = q.exp()
 
 # Rotate vectors
 vector = jnp.array([1.0, 0.0, 0.0])
@@ -120,7 +136,7 @@ rotated_batch = batch_rotate(q_batch, vectors)
 ### SLERP
 ```python
 # Smooth rotation interpolation
-q_start = Quaternion.ones()
+q_start = Quaternion(1.0)
 q_end = Quaternion.from_rotation_matrix(rotation_matrix)
 
 # Generate smooth interpolation

{fastquat-0.5.2 → fastquat-1.0b2}/README.md

@@ -30,13 +30,28 @@ import jax.numpy as jnp
 from fastquat import Quaternion
 
 # Create quaternions
-q1 = Quaternion.ones()  # Identity quaternion
+q1 = Quaternion(1)  # Identity quaternion
 q2 = Quaternion(0.7071, 0.7071, 0.0, 0.0)  # 90° rotation around x-axis
+q = Quaternion(1.0, 0.1, 0.2, 0.3)
+p = 2
 
-# Quaternion operations
-q3 = q1 * q2  # Multiplication
-q_inv = 1 / q1           # Inverse, or q1 ** -1
-q_norm = q1.normalize()  # Normalization
+# Arithmetic
+q_sum = q1 + q2
+q_diff = q1 - q2
+q_product = q1 * q2
+q_power = q**p
+
+# Normalization
+norm = abs(q)  # Quaternion norm
+q_unit = q.normalize()  # Unit quaternion
+
+# Conjugation and inverse
+q_conj = q.conj()  # Conjugate
+q_inv = 1 / q  # Inverse, or q ** -1
+
+# Other operations
+q_log = q.log()
+q_exp = q.exp()
 
 # Rotate vectors
 vector = jnp.array([1.0, 0.0, 0.0])
@@ -98,7 +113,7 @@ rotated_batch = batch_rotate(q_batch, vectors)
 ### SLERP
 ```python
 # Smooth rotation interpolation
-q_start = Quaternion.ones()
+q_start = Quaternion(1.0)
 q_end = Quaternion.from_rotation_matrix(rotation_matrix)
 
 # Generate smooth interpolation

fastquat-1.0b2/docs/README.md

@@ -0,0 +1,27 @@
+# Documentation Build Instructions
+
+This documentation uses **PEP 735 dependency groups** instead of separate requirements files to avoid duplication.
+
+
+## Building Documentation Locally
+
+The dependency group `docs` is included in the group `dev` which is installed by default when using  ̀uv` (recommended).
+No extra step other than setting up and activating the virtual environment is required:
+```bash
+# From the docs/ directory
+uv sync --locked --group cuda12
+source .venv/bin/activate
+```
+
+If you're not using uv, you can install the docs dependencies manually:
+```bash
+# Install the project with docs dependencies (pip >= 25.1)
+pip install --upgrade pip
+pip install -e . --group dev
+```
+
+Then build the docs
+```bash
+cd docs
+make html
+```

{fastquat-0.5.2 → fastquat-1.0b2}/docs/source/api/quaternion.md

@@ -39,7 +39,7 @@ compilation, automatic differentiation, and vectorization.
 ## Core Operations
 
 ```{eval-rst}
-.. automethod:: fastquat.Quaternion.norm
+.. automethod:: fastquat.Quaternion.__abs__
 .. automethod:: fastquat.Quaternion.normalize
 .. automethod:: fastquat.Quaternion.conjugate
 .. automethod:: fastquat.Quaternion.conj

{fastquat-0.5.2 → fastquat-1.0b2}/docs/source/conf.py

@@ -4,6 +4,9 @@
 import os
 import sys
 
+# Force JAX to use CPU only (must be set before JAX is imported)
+os.environ['JAX_PLATFORMS'] = 'cpu'
+
 # Add the source path
 sys.path.insert(0, os.path.abspath('../../src'))
 

{fastquat-0.5.2 → fastquat-1.0b2}/docs/source/development.md

@@ -105,36 +105,58 @@ FastQuat is designed for high performance. When contributing:
 Here's how to add a new method to the Quaternion class:
 
 ```python
-def new_method(self, parameter: Array) -> Quaternion:
-    """Brief description of what the method does.
-
-    Args:
-        parameter: Description of the parameter
-
-    Returns:
-        Description of the return value
-    """
-    # Implementation using JAX operations
-    result = jnp.some_operation(self.wxyz, parameter)
-    return Quaternion.from_array(result)
+from typing import Self
+
+import jax.numpy as jnp
+from jax.typing import ArrayLike
+
+
+class Quaternion:
+   ...
+   def new_method(self, parameter: ArrayLike) -> Self:
+       """Brief description of what the method does.
+
+       Args:
+           parameter: Description of the parameter
+
+       Returns:
+           Description of the return value
+       """
+       # Implementation using JAX operations
+       parameter = jnp.asarray(parameter)
+       result = jnp.some_operation(self.wxyz, parameter)
+       return Quaternion.from_array(result)
 ```
 
 Then add tests:
 
 ```python
+import jax
+import jax.numpy as jnp
+import pytest
+
+from fastquat import Quaternion
+
+
+@pytest.mark.parametrize(
+   'parameter, expected_values',
+   [
+      (..., ...),
+   ]
+)
 @pytest.mark.parametrize('do_jit', [False, True])
-def test_new_method(do_jit):
+def test_new_method(parameter, expected_values, do_jit):
     """Test the new method."""
-    def test_fn(q, param):
-        return q.new_method(param)
+    def test_fn(q_, parameter_):
+        return q_.new_method(parameter_)
 
     if do_jit:
-        test_fn = jax.jit(test_fn)
+        test_fn = jax.jit(test_fn, static_argnums=1)
 
     # Test implementation
-    q = Quaternion.ones()
+    q = Quaternion(1.0)
     result = test_fn(q, parameter)
-    assert jnp.allclose(result.wxyz, expected_result)
+    assert jnp.allclose(result.wxyz, expected_values)
 ```
 
 ## Documentation

{fastquat-0.5.2 → fastquat-1.0b2}/docs/source/index.md

@@ -19,55 +19,52 @@ FastQuat provides optimized quaternion operations with full JAX compatibility, f
 ## Quick Start
 
 ```python
-import jax.numpy as jnp
 from fastquat import Quaternion
 
 # Create quaternions
-q1 = Quaternion.ones()  # Identity quaternion
+q1 = Quaternion(1.0)  # Identity quaternion
 q2 = Quaternion(0.7071, 0.7071, 0.0, 0.0)  # 90° rotation around x-axis
-
-# Quaternion operations
-q3 = q1 * q2  # Multiplication
-q_inv = 1 / q1  # Inverse
-q_norm = q1.normalize()  # Normalization
-
-# Rotate vectors
-vector = jnp.array([1.0, 0.0, 0.0])
-rotated = q2.rotate_vector(vector)
-
-# Spherical interpolation (SLERP)
-interpolated = q1.slerp(q2, t=0.5)  # Halfway between q1 and q2
 ```
 
-## Contents
+## Quaternion Operations
+
+| Operation | Syntax | Description |
+|-----------|--------|-------------|
+| Addition | `q1 + q2` | Component-wise addition |
+| Subtraction | `q1 - q2` | Component-wise subtraction |
+| Multiplication | `q1 * q2` | Hamilton product |
+| Exponentiation | `q ** p` | Quaternion power |
+| Inverse | `1 / q` | Multiplicative inverse |
+| Norm | `abs(q)` | Quaternion magnitude |
+| Normalization | `q.normalize()` | Unit quaternion |
+| Conjugate | `q.conj()` | Quaternion conjugate |
+| Rotation | `q.rotate_vector(v)` | Rotate 3D vector |
+| SLERP | `q1.slerp(q2, t)` | Spherical interpolation |
+| Log | `q.log()` | Quaternion logarithm |
+| Exp | `q.exp()` | Quaternion exponential |
 
 ```{toctree}
 :maxdepth: 2
 :caption: User Guide
 
-installation.md
-quickstart.md
-```
-
-```{toctree}
-:maxdepth: 2
-:caption: Examples
-
-examples/index.md
+user-guide/installation
+user-guide/getting-started
+user-guide/tutorial-rotations
+user-guide/tutorial-slerp
 ```
 
 ```{toctree}
 :maxdepth: 2
 :caption: API Reference
 
-api/index
+api/quaternion
 ```
 
 ```{toctree}
 :maxdepth: 1
 :caption: Development
 
-development.md
+development
 ```
 
 ## Indices and tables

fastquat-1.0b2/docs/source/user-guide/getting-started.ipynb

@@ -0,0 +1,293 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Getting Started\n",
+    "\n",
+    "This guide will get you started with FastQuat's core functionality."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Creating Quaternions\n",
+    "\n",
+    "There are several ways to create quaternions:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import jax\n",
+    "import jax.numpy as jnp\n",
+    "import jax.random as jr\n",
+    "\n",
+    "from fastquat import Quaternion\n",
+    "\n",
+    "# From components (w, x, y, z)\n",
+    "q1 = Quaternion(0.0, -1.0, -1.0, -1.0)\n",
+    "\n",
+    "identity = Quaternion(1.0)\n",
+    "i = Quaternion(x=1)\n",
+    "j = Quaternion(y=1)\n",
+    "k = Quaternion(z=1)\n",
+    "\n",
+    "# Convenience constructors\n",
+    "q_zeros = Quaternion.zeros((2, 3))\n",
+    "q_ones = Quaternion.ones((2, 3))\n",
+    "q_twos = Quaternion.full((2, 3), 2)\n",
+    "\n",
+    "# From arrays\n",
+    "array = jnp.array([1.0, 0.0, 0.0, 0.0])\n",
+    "q2 = Quaternion.from_array(array)\n",
+    "\n",
+    "# Random normalized quaternions\n",
+    "key = jr.key(42)\n",
+    "q_random = Quaternion.random(key)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Basic Operations\n",
+    "\n",
+    "Quaternions support standard mathematical operations:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "q = Quaternion(1.0, 0.1, 0.2, 0.3)\n",
+    "p = 2\n",
+    "\n",
+    "# Arithmetic\n",
+    "q_sum = q1 + q2\n",
+    "q_diff = q1 - q2\n",
+    "q_product = q1 * q2\n",
+    "q_power = q**p\n",
+    "\n",
+    "# Normalization\n",
+    "norm = abs(q)  # Quaternion norm\n",
+    "q_unit = q.normalize()  # Unit quaternion\n",
+    "\n",
+    "# Conjugation and inverse\n",
+    "q_conj = q.conj()  # Conjugate\n",
+    "q_inv = 1 / q  # Inverse, or q ** -1\n",
+    "\n",
+    "# Other operations\n",
+    "q_log = q.log()\n",
+    "q_exp = q.exp()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Vector Rotation\n",
+    "\n",
+    "One of the most common uses of quaternions is rotating 3D vectors:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Create a 90° rotation around the z-axis\n",
+    "angle = jnp.pi / 2\n",
+    "q_rot = Quaternion(jnp.cos(angle / 2), 0.0, 0.0, jnp.sin(angle / 2))\n",
+    "\n",
+    "# Rotate a vector\n",
+    "vector = jnp.array([1.0, 0.0, 0.0])  # Unit vector along x\n",
+    "rotated = q_rot.rotate_vector(vector)\n",
+    "print(rotated)  # Should be approximately [0, 1, 0]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Conversion to/from Rotation Matrices\n",
+    "\n",
+    "FastQuat can convert between quaternions and rotation matrices:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Quaternion to rotation matrix\n",
+    "R = q_rot.to_rotation_matrix()\n",
+    "print(R.shape)  # (3, 3)\n",
+    "\n",
+    "# Rotation matrix to quaternion\n",
+    "q_from_matrix = Quaternion.from_rotation_matrix(R)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Spherical Linear Interpolation (SLERP)\n",
+    "\n",
+    "SLERP provides smooth interpolation between quaternions:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Two different orientations\n",
+    "q_start = Quaternion(1.0)  # Identity\n",
+    "q_end = Quaternion(0.7071, 0.7071, 0.0, 0.0)  # 90° around x\n",
+    "\n",
+    "# Interpolate between them\n",
+    "t = 0.5  # Halfway point\n",
+    "q_mid = q_start.slerp(q_end, t)\n",
+    "\n",
+    "# Batch interpolation\n",
+    "t_values = jnp.linspace(0, 1, 10)\n",
+    "interpolated = q_start.slerp(q_end, t_values)\n",
+    "print(interpolated.shape)  # (10,) - 10 quaternions"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## JAX Integration\n",
+    "\n",
+    "FastQuat is fully compatible with JAX transformations:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# JIT compilation\n",
+    "@jax.jit\n",
+    "def rotate_and_normalize(q, v):\n",
+    "    rotated = q.rotate_vector(v)\n",
+    "    return rotated / jnp.linalg.norm(rotated)\n",
+    "\n",
+    "\n",
+    "# Vectorization\n",
+    "batch_rotate = jax.vmap(lambda q, v: q.rotate_vector(v))\n",
+    "\n",
+    "# Create batches\n",
+    "q_batch = Quaternion.random(key, shape=(100,))\n",
+    "v_batch = jax.random.normal(key, (100, 3))\n",
+    "\n",
+    "# Process entire batch at once\n",
+    "rotated_batch = batch_rotate(q_batch, v_batch)\n",
+    "\n",
+    "\n",
+    "# Automatic differentiation\n",
+    "def loss_function(q_params):\n",
+    "    q = Quaternion.from_array(q_params)\n",
+    "    rotated = q.rotate_vector(vector)\n",
+    "    return jnp.sum(rotated**2)\n",
+    "\n",
+    "\n",
+    "grad_fn = jax.grad(loss_function)\n",
+    "gradients = grad_fn(jnp.array([1.0, 0.1, 0.1, 0.1]))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Performance Tips\n",
+    "\n",
+    "1. **Use JIT compilation** for repeated operations:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "@jax.jit\n",
+    "def batch_operation(quaternions):\n",
+    "    return quaternions.normalize()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "2. **Prefer batch operations** over loops:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Good: vectorized operation\n",
+    "results = q_batch.rotate_vector(v_batch)\n",
+    "\n",
+    "# Avoid: Python loops\n",
+    "# results = [q.rotate_vector(v) for q, v in zip(q_batch, v_batch)]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "3. **Normalize quaternions** when needed for rotations:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "q_unit = q.normalize()  # Ensure unit quaternion for rotations"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Next Steps\n",
+    "\n",
+    "* Explore the tutorials for detailed use cases\n",
+    "* Check the [API reference](../api/quaternion.md) for complete API documentation\n",
+    "* See advanced interpolation techniques with SLERP"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}