CliffordNumbers improvements

[AndersEdin]

Add math primitives, AD/GPU/SoA extensions, and performance fast paths

This branch consolidates the CliffordNumbers 0.2.0-dev work: a blade/versor structure API with general log/sqrt, parity-correct Pin-group support, three new package extensions (ChainRulesCore, StructArrays, Adapt), a benchmark suite with the performance fixes it motivated, and Julia 1.10 LTS support.

New features

• Blade/versor structure API: isblade (Plücker relations, checked metric-free) and isversor (parity, scalar x x̃, grade preservation of the twisted conjugation); factor_blade (orthogonal 1-vector factors whose wedge reproduces the blade in any signature) and factor_versor (Cartan–Dieudonné reflection peeling, with exact resolution of null-displacement residuals); bivector_decomposition made a public function.
• General log and sqrt on multivectors, on their principal branches: study numbers s + n with n² scalar (elliptic, hyperbolic, and parabolic closed forms, including odd-grade blades) and even multivectors with positive x x̃.
• log and sqrt on rotors (EvenCliffordNumber): simple-bivector closed form plus invariant decomposition with Newton polish for dim ≥ 4; parity with Quaternions.jl on the VGA(3) rotor subalgebra.
• Parity-correct odd-versor (Pin group) support: sandwich now uses the twisted conjugation for odd versors so a mirror acts as the proper reflection -u v u⁻¹ on every operand grade; mirror_peel gives the canonical normal form V = v · R of an odd versor; one of an odd carrier is the even identity of the same algebra.
• det and tr of Clifford numbers.
• metric_tuple: world-age-robust source of metric data for custom signatures.
• ChainRulesCore extension for reverse-mode AD: rrules for the geometric product (exact Cayley-transpose pullback, correct in every signature), scalar *//, the four grade automorphisms, scalar_product, abs2, and +/-, plus a ProjectTo that projects cotangents onto the primal's grade structure.
• StructArrays extension: structure-of-arrays layout for KVector and Z2CliffordNumber, giving each blade coefficient its own column.
• Adapt extension and GPU enablement: scalar-type mapping across the inner NTuple, allocation-free constructor validation, GPU-safe grade automorphisms and complement/dual family — verified end-to-end on an RTX 3070.
• Julia 1.10 LTS support: compat lower bound raised to 1.10 across the package.

New tests

• Theorem-based test suite (test/theorems.jl) checking algebraic identities.
• Factorization and Pin-versor suites (test/factorization.jl, test/pin_versors.jl) covering the new structure API and odd-versor semantics.
• Custom-signature suite (test/custom_signature.jl) exercising user-defined metrics end to end.
• Extension test suites for ChainRulesCore (pullbacks validated against central finite differences), StructArrays, Adapt, and expanded Quaternions parity checks.
• Columnar-broadcast regression tests locking in the guarantee that broadcast preserves SoA layout and allocates only the output.
• Determinant/trace, BitIndices, and rotor-product coverage; expanded test/operations.jl.
• Algebra-drift regression checks built into every benchmark workload via Julia-primitive references.

Fixed defect

• exp of a mixed-signature bivector with abs2 ∈ (-1, 0) threw; the Taylor-scaling is now clamped.
• On Julia 1.10, dimension of a plain Signature returned Int8, sending binomial down the Float64 gamma-function fallback — nblades of a KVector in a custom-signature algebra returned a Float64 and broke construction. It now returns a full-width Int.

Performance improvements

• left_complement/right_complement are now @generated with all coefficient positions and signs baked at compile time, replacing the runtime indexing path that made the regressive product (join) lag.
• Validation-free inv for EvenCliffordNumber over VGA(2) (ℂ) and VGA(3) (ℍ) via a closed-form versor inverse, plus closed-form abs2 for those positive-definite even subalgebras.
• @generated closed-form * and ^2 for the 2-component spinor.
• Closed-form reverse(::KVector).
• New bench/ suite (harness, complex/quaternion/multivector workloads, recorded baselines) benchmarking against Julia primitives — this drove all of the fixes above and documents the remaining PGA(3) motor-inverse hot spot.

Documentation

• New custom-signatures tutorial (docs/src/custom_signatures.md) on defining your own metric signature.
• New extensions page (docs/src/extensions.md) covering Zygote/ChainRulesCore usage, StructArrays, and Adapt.
• API pages extended with the determinant, factorization, and metrics additions.
• Documentation build fixed: reattached a detached docstring, repaired broken cross-references, and included the previously orphaned determinant docstrings in an API page.
• Bench README and recorded results consolidated into per-group files (complex/quaternion/multivector); docs and code comments tightened to house style.

---

This work was done with support from Claude Code.

[brainandforce]

I greatly appreciate your interest, but I cannot merge this PR for a few reasons.

First of all, this is far too much code for me to review at once. If you can re-file this as multiple PRs corresponding to each feature or fix, then I can work on them much more effectively. I haven't worked on this codebase actively in a while, so I'd need to get up to speed with my own work again, admittedly.

Second, I will have to manually review the code here. In my experience, LLMs do not have adequate coverage of geometric algebra, and often get important details incorrect. This is in part due to the lack of standardized conventions, or conventions that deliberately break from commonly used language in the study of Clifford algebras (e.g. what is a "spinor" in this context?), and as much as possible I would like to avoid bogging down the code and documentation in the traditional approach to Clifford algebras or contradictory conventions. The code in this repo is intentionally written to facilitate study for people who are not familiar with geometric algebra or numerical approaches to it.

Third, this is an MIT licensed library, and there are GPL licensed libraries that cover Clifford algebras (among other things) written in Julia. I am concerned about code generated by an LLM reproducing code from one of these GPL libraries, which could lead to a copyright violation.

If you wish to continue this work/file this as separate PRs, my preference for order of operations is:

• Any bug fixes that apply to the main branch's current state, including documentation issues
• Increased test coverage
• Performance improvements and benchmarks (though keep numerical stability in mind!)
• New features:
  • log/sqrt implementations
  • Versor/blade tools
  • Autodiff support (ChainRulesCore extension). Don't worry about forward mode AD yet, because I'd like to try a different approach to this that exploits the fact that the dual numbers are a Clifford algebra.
  • sandwich, but if it is either more efficient or more numerically stable than a simple - a' * x * a
  • Changes to enable/improve GPU support

I hope this doesn't dissuade you from contributing - again, I do appreciate the interest. I see this is your first PR, so I figure learning some of the conventions about code contribution will come with time (it's something I'm still learning myself!)