Using clifra with PyTorch

Clifra complements PyTorch. It supplies Clifford-specific representation, planning, products, actions, metrics, and selected geometric parameterizations. PyTorch remains the tensor runtime and the surrounding machine-learning system.

Clifford structure belongs in the parts of a model where grades, signatures, or generated geometric actions carry meaning. Other components can remain ordinary PyTorch tensor operations.

Division of work

Concern	Primary owner
Signature, blades, grades, and layout conversion	clifra
Static Clifford product and action planning	clifra
Bivector exponential routes and spectral diagnostics	clifra
Tagged spin/sphere parameter handling	clifra
Tensor storage, devices, dtypes, and autograd	PyTorch
General modules, channel mixing, losses, and optimizers	PyTorch
Data loading, distributed execution, AMP, and deployment	PyTorch and the application
Scientific constraints and validation	The application

Planned clifra executors are torch.nn.Module objects with structural indices and coefficients stored as buffers. Their runtime path is ordinary tensor work, so gradients pass into the inputs and learnable parameters through PyTorch's existing autograd system.

Use geometry where it changes the model

Clifra is applicable when at least one of the following is part of the model's semantics:

• parameters are vectors, bivectors, versors, or declared mixed-grade objects;
• a transformation should be generated by a Clifford exponential or sandwich action;
• the signature expresses a required metric or null structure;
• grade projection removes components that should not exist;
• an algebraic invariant is more meaningful than an unconstrained tensor map.

Use ordinary PyTorch for generic feature extraction, embeddings, channel mixing, attention outside Clifford structure, readout heads, and losses that do not require algebraic products. Passing every intermediate through a full multivector representation adds cost without adding semantics.

Plan once and execute repeatedly

Clifra separates structural discovery from the hot tensor path. Construct layouts and planned layers in module initialization, then reuse them in forward:

import torch
import torch.nn as nn

from clifra.core import make_algebra


class BivectorProduct(nn.Module):
    def __init__(self, n: int) -> None:
        super().__init__()
        self.algebra = make_algebra(n, 0, device="cpu", dtype=torch.float32)
        self.bivectors = self.algebra.layout((2,))
        self.even = self.algebra.layout(range(0, n + 1, 2))
        self.product = self.algebra.plan_product(
            op="gp",
            left_layout=self.bivectors,
            right_layout=self.bivectors,
            output_layout=self.even,
        )

    def forward(self, left: torch.Tensor, right: torch.Tensor) -> torch.Tensor:
        return self.product(left, right)

Planning inside every batch repeats Python-side basis analysis and prevents the module boundary from expressing a stable contract. Reusing a plan also gives compilation a fixed tensor program.

Compilation support remains backend- and operation-specific. A graph can be captured successfully while a particular compiler backend fails to lower one of its scatter, matrix-exponential, or decomposition operations. Such a failure reflects backend capability; by itself, it says nothing about algebraic correctness. Successful compilation and numerical correctness likewise require separate checks.

Design sequence

1. Choose the signature from the geometry, not from the fastest benchmark.
2. Declare the narrowest layouts that express each object.
3. Select the Clifford action that enforces useful structure.
4. Keep generic tensor processing in PyTorch.
5. Inject planning and exponential policy for the target device, dtype, batch, and workload.
6. Decide explicitly whether each loss uses coefficient-lane geometry or a signed Clifford form.
7. Validate numerical routes and complete model-level constraints.

For spectral-local exponentiation, this sequence includes inspecting the actual angle spectra and accumulated drift. For a full-layout product, it includes accepting the canonical lane and pair cost explicitly. Policy can select among implemented routes; it cannot make an unsuitable representation cheap.

Common design mistakes

• Using full layouts by default. Full storage is appropriate when the model needs all grades, not as a substitute for deciding what a tensor means.
• Inferring meaning from width. A final-axis size does not identify a grade layout; preserve the contract.
• Treating lane norm as signature norm. The first is positive coefficient geometry, while the second is a signed algebraic form.
• Attributing a model-wide property to one layer. A rotor action may be isometric while surrounding mixing and readout are not.
• Treating policy weights as universal performance facts. Tune them on the intended hardware and workload when defaults are inadequate.
• Equating compiler failure with operation failure. Confirm eager execution and numerical behavior separately from backend lowering.

Practical limits

Full-grade layouts retain exponential basis growth, and a mathematically valid plan can still exceed device capacity. Spectral-local exponentiation has signature and rank constraints. Objectives, data, physical constraints, and identifiability arguments come from the application, outside the geometric parameterization.

The algebra host and execution engine support research modules, geometric deep learning, scientific computation, and isolated Clifford operations. The stated limits identify decisions that remain with the application.

PyTorch provides the general differentiable computing environment. Clifra adds explicit Clifford structure. Scientific and modeling conclusions belong to the application.