Quaternion Ruffle Field

A Novel Neural Architecture Where Neurons Know Which Way They're Pointing

Innovation • Benchmarks • Installation • Quick Start • Architecture • Citation

🏆 Headline Results

3D Rotation Prediction

Model	Accuracy	Parameters
QRF (Ours)	92.6%	152K
QRF (No Attention)	87.4%	131K
Dense MLP	85.4%	18K
Transformer	78.6%	398K
LSTM	71.8%	202K

🥇 QRF Wins!

+7.2% over best baseline

2.6x fewer parameters than Transformer

Quaternions naturally encode rotation — QRF leverages this inductive bias

🌟 What is Quaternion Ruffle Field?

Quaternion Ruffle Field (QRF) is a novel neural network architecture where each neuron maintains both a spatial position and a rotational orientation represented as a unit quaternion. Unlike traditional scalar neurons, QRF neurons exist on a dynamic manifold (S³) and interact through geometric relationships.

🧠 Traditional Neuron

Value: 0.73

Just a number. No direction. No orientation memory.

🔮 Quaternion Neuron

Position:    [x, y, z, w] ∈ ℝ⁴
Orientation: q = w + xi + yj + zk ∈ S³

A point in space that knows which way it's pointing!

💡 The Core Insight

Traditional neural networks treat rotation as just another pattern to learn. QRF builds rotation into the neuron itself — each neuron IS a rotation. This creates a powerful inductive bias for tasks involving 3D geometry, orientation, and rotational relationships.

🚀 Key Features

🔄

Dual-State Neurons
_{Position + Orientation}

🌡️

Field Thermodynamics
_{Adaptive Temperature & Coherence}

🧠

Sequence Memory
_{Cross-Timestep Attention}

💾

SLERP Memory
_{Spherical Interpolation}

⚡

Ruffle Optimizer
_{Energy-Based Exploration}

✨ What Makes QRF Different

Feature	Traditional NN	QRF	Benefit
Neuron State	Scalar value	Position + Quaternion	Native rotation representation
Interactions	Matrix multiply	Hamilton products + Geodesics	Preserves rotational composition
Attention	Learned from scratch	Modulated by quaternion state	Geometry-aware weighting
Memory	Hidden states	SLERP on S³ manifold	Smooth orientation interpolation
Dynamics	Static weights	Temperature + Coherence evolution	Automatic regularization
Optimization	Gradient only	Gradient + Ruffle perturbations	Escapes local minima

📊 Benchmark Results

Task 1: 3D Rotation Prediction

Given 64 noisy point correspondences (before/after rotation), predict the rotation quaternion.

Model              Accuracy    Params      Time(s)    
─────────────────────────────────────────────────────
🥇 QRF             92.60%      151,641     180.1      
🥈 QRF_NoAttn      87.40%      131,077     163.5      
🥉 Dense           85.40%      18,436      32.9       
   Transformer     78.60%      398,212     502.0      
   LSTM            71.80%      202,500     138.6

Why QRF excels: Quaternions naturally compose rotations. The sequence memory aggregates evidence from all 64 point pairs simultaneously.

Task 2: Long-Term Memory

Remember a pattern from sequence start, recall after noise-filled gap.

Model              Accuracy    Params      
─────────────────────────────────────────
   Transformer     100.0%      413,828     
   LSTM            100.0%      264,964     
   QRF             100.0%      167,257     
   QRF_NoAttn      100.0%      146,693     
   Dense           58.6%       34,052

Note: QRF matches Transformer/LSTM with 2.5x fewer parameters.

Task 3: Sequence Classification

Classify sequences based on embedded prototype patterns.

Model              Accuracy    Params      
─────────────────────────────────────────
   All models      100.0%      Various

All models solve this task perfectly — it's included as a sanity check.

Field Dynamics (What Makes QRF Unique)

During training, QRF's field state evolves:

Metric          Start       End         Meaning
──────────────────────────────────────────────────────
Energy          ~1.3        0.93        Field becoming more organized
Temperature     1.0         0.51        Cooling → sharper decisions
Coherence       1.0         0.58        Neurons aligning orientations

These dynamics provide automatic regularization — the field self-organizes!

📦 Installation

Prerequisites

Python 3.9+ and PyTorch 2.0+

Via pip

pip install quaternion-ruffle-field

From Source

git clone https://github.com/reneemgagnon/quaternion-ruffle-field.git
cd quaternion-ruffle-field
pip install -e .

Requirements

torch>=2.0.0
numpy>=1.24.0

⚡ Quick Start

Basic Usage

import torch
from quaternion_ruffle_field import QRFModel

# Create model for rotation prediction (output_dim=4 for quaternion)
model = QRFModel(
    input_dim=6,           # e.g., 3D point + rotated point
    hidden_dim=128,
    output_dim=4,          # quaternion output
    n_neurons=64,
    use_attention=True,
    use_sequence_memory=True  # NEW in v5.0!
)

# Forward pass
x = torch.randn(32, 64, 6)  # [batch, sequence, features]
quaternions = model(x)       # [batch, sequence, 4] - unit quaternions!

print(f"Output shape: {quaternions.shape}")
print(f"Is unit quaternion: {torch.allclose(quaternions.norm(dim=-1), torch.ones(32, 64))}")

With Ruffle Optimization

from quaternion_ruffle_field import QRFModel, QuaternionRuffleOptimizer

model = QRFModel(input_dim=6, hidden_dim=128, output_dim=4, n_neurons=64)
optimizer = torch.optim.AdamW(model.parameters(), lr=1e-3)
qrf_optimizer = QuaternionRuffleOptimizer(model.field, fold_threshold=1.5)

for epoch in range(30):
    for batch in dataloader:
        optimizer.zero_grad()
        
        output = model(batch['input'])
        loss = quaternion_loss(output, batch['target'])
        
        loss.backward()
        optimizer.step()
        
        # Apply quaternion ruffles (energy-based perturbations)
        stats = qrf_optimizer.step()
    
    print(f"Epoch {epoch}: Energy={stats['energy']:.3f}, T={stats['temperature']:.3f}")

Memory-Aware Processing

# Process first sequence
out1 = model(sequence_1)

# Reset field but preserve learned state
model.field.reset(preserve_memory=True)

# Process second sequence (can recall previous context)
out2 = model(sequence_2)

# Explicitly restore from memory with SLERP blending
model.field.restore_from_memory(blend_factor=0.5)

🏗️ Architecture

System Overview

┌──────────────────────────────────────────────────────────────────────────────┐
│                         QUATERNION RUFFLE FIELD v5.0                          │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                               │
│  INPUT                    SEQUENCE MEMORY                  FIELD PROCESSING  │
│  ─────                    ──────────────                  ─────────────────  │
│                                                                               │
│  [batch, seq, dim]   ──►  Cross-Timestep    ──►  ┌─────────────────────┐    │
│                           Attention               │  Quaternion Field   │    │
│                           (Q, K, V)               │  ┌───┐ ┌───┐ ┌───┐ │    │
│                           │                       │  │ q │ │ q │ │ q │ │    │
│                           ▼                       │  └─┬─┘ └─┬─┘ └─┬─┘ │    │
│                     Temperature-                  │    │     │     │   │    │
│                     Modulated                     │    └─────┴─────┘   │    │
│                     Softmax                       │    Hamilton Products│    │
│                           │                       └──────────┬──────────┘    │
│                           ▼                                  │               │
│                     Gated Memory                             ▼               │
│                     Integration              ┌───────────────────────────┐   │
│                           │                  │   Quaternion Modulation   │   │
│                           │                  │   + Cached Attention      │   │
│                           │                  │   + Skip Connections      │   │
│                           │                  └───────────────────────────┘   │
│                           │                                  │               │
│                           └──────────────────────────────────┘               │
│                                              │                               │
│                                              ▼                               │
│                                    OUTPUT [batch, seq, dim]                  │
│                                                                               │
├──────────────────────────────────────────────────────────────────────────────┤
│  FIELD DYNAMICS (Updated during training)                                     │
│  ────────────────────────────────────────                                     │
│                                                                               │
│  🌡️ Temperature ──► Controls attention sharpness (lower = more focused)      │
│  🧲 Coherence   ──► Measures neuron alignment (higher = more organized)       │
│  ⚡ Energy      ──► Triggers ruffle perturbations (prevents stagnation)       │
│                                                                               │
└──────────────────────────────────────────────────────────────────────────────┘

The Mathematics

Quaternion Representation:

q = w + xi + yj + zk    where    w² + x² + y² + z² = 1

Hamilton Product (Neuron Interaction):

q₁ ⊗ q₂ = (w₁w₂ - x₁x₂ - y₁y₂ - z₁z₂) +
          (w₁x₂ + x₁w₂ + y₁z₂ - z₁y₂)i +
          (w₁y₂ - x₁z₂ + y₁w₂ + z₁x₂)j +
          (w₁z₂ + x₁y₂ - y₁x₂ + z₁w₂)k

SLERP (Memory Blending):

slerp(q₁, q₂, t) = sin((1-t)θ)/sin(θ) · q₁ + sin(tθ)/sin(θ) · q₂
where θ = arccos(q₁ · q₂)

Geodesic Distance:

d(q₁, q₂) = arccos(|q₁ · q₂|)

🎯 Use Cases

🤖 Robotics Pose estimation, motion planning, joint angle prediction	🧬 Molecular Protein folding, molecular docking, conformational analysis	🎮 3D Vision Object pose estimation, camera calibration, SLAM
🛸 Aerospace Satellite orientation, flight dynamics, trajectory prediction	🎬 Animation Motion capture, skeletal animation, rotation interpolation	🔬 Physics Spin systems, quantum states, rotational dynamics

📚 API Reference

QRFModel

class QRFModel(nn.Module):
    """
    Complete QRF model for end-to-end training.
    
    Parameters
    ----------
    input_dim : int
        Input feature dimension
    hidden_dim : int
        Hidden representation dimension
    output_dim : int
        Output dimension (use 4 for quaternion output)
    n_neurons : int, default=64
        Number of neurons in quaternion field
    use_attention : bool, default=True
        Enable quaternion-modulated attention
    use_sequence_memory : bool, default=True
        Enable cross-timestep sequence memory (NEW in v5.0)
    use_memory : bool, default=True
        Enable field state memory preservation
    """