DeepCausality Multivector

A dynamic, universal Clifford Algebra implementation for Rust, designed for theoretical physics, causal modeling, and geometric algebra applications.

Features

• Dynamic Metric Signature: Supports arbitrary signatures $Cl(p, q, r)$ at runtime via the Metric enum.
  • Euclidean, Non-Euclidean, Minkowski, PGA, and Custom signatures.
• Universal Multivector: A single type CausalMultiVector<T> can represent scalars, vectors, bivectors, and higher-grade blades.
• Comprehensive Operations:
  • Geometric Product, Outer Product, Inner Product (Left Contraction).
  • Reversion, Squared Magnitude, Inverse, Dual.
  • Grade Projection.
• Higher-Kinded Types (HKT): Implements Functor, Pure, Applicative, Foldable, and CoMonad (via deep_causality_haft) for advanced functional patterns.
  • There is deliberately no Monad. See Higher-Kinded Types for the reason.

Pre-configured Algebras

Complex

Algebras:

• $Cl_{\mathbb{C}}(2)$ (Complex Quaternions): The minimal complex Clifford algebra, often used for $\mathfrak{spin}(3, 1)$ representations.
• $Cl_{\mathbb{C}}(4)$ (Quaternion Operator Algebra): Hosts the $\mathfrak{spin}(4) \sim \mathfrak{su}(2)_L \oplus \mathfrak{su}(2)R$ electroweak symmetries. ($\mathcal{M}{\mathbb{H}}$)
• $Cl_{\mathbb{C}}(6)$ (Octonion Operator Algebra): Hosts the $\mathfrak{spin}(6) \sim \mathfrak{su}(4)$ Pati-Salam symmetries, and the colour group $\mathfrak{su}(3)C$. ($\mathcal{L}{\mathbb{O}}$)
• $Cl_{\mathbb{C}}(8)$ (Dixon Left Multiplication Algebra): Hosts $\mathfrak{spin}(8)$ triality. ($\mathcal{L}_{\mathcal{A}}$)
• $Cl_{\mathbb{C}}(10)$ (Grand Unified Algebra): Hosts the full $\mathfrak{spin}(10)$ gauge symmetry. ($\mathcal{M}_{\mathcal{A}}$)

Type: ComplexMultiVector

Real

Algebras:

• $Cl(N, 0)$: Generic N-dimensional Euclidean algebra.
• $Cl(0, 1)$: Isomorphic to Complex Numbers $\mathbb{C}$.
• $Cl(1, 0)$: Isomorphic to Split-Complex (Hyperbolic) Numbers.
• $Cl(0, 2)$: Isomorphic to Quaternions $\mathbb{H}$.
• $Cl(2, 0)$: Isomorphic to Split-Quaternions (Coquaternions) / $\text{Mat}(2, \mathbb{R})$.
• $Cl(3, 0)$: Algebra of Physical Space (APS) / Pauli Algebra.
• $Cl(1, 3)$ / $Cl(3, 1)$: Space-Time Algebra (STA) / Dirac Algebra (with two different conventions).
• $Cl(4, 1)$: Conformal Geometric Algebra (CGA).

Type: RealMultiVector

Quantum State Vector (HilbertState)

The HilbertState type represents a quantum state vector (ket) $|\psi\rangle$ within a Clifford Algebra. It acts as a strong type for elements of a minimal left ideal of the algebra, which serves as the Hilbert space.

• Coefficients: Always Complex<f64>.
• Metric: Fixed at construction, typically Cl(0,10) (NonEuclidean, 10D) for the Grand Unified Algebra ($\mathfrak{spin}(10)$).

This ensures type safety and prevents mixed-algebra operations, crucial for consistent quantum mechanical calculations within the algebraic framework.

Type: HilbertState (Alias for CausalMultiVector<Complex<f64>> with specific constructors)

3D Projective Geometric Algebra

Type: PGA3DMultiVector

Custom Algebras

1. Define a custom metric
2. Instantiate either a real, complex, or custom typed MultiVector with the metric
3. Done

use deep_causality_multivector::{RealMultiVector, Metric};

   // Some data 
   let data = vec![0.0; 16];

   // Define a custom metric. See docs for Metrics about Generic or Custom metric type 
   let metric =  Metric::Custom {
                dim: 4,
                neg_mask: 1,
                zero_mask: 0,
            },

   // Instantaiate your custom algebra over a RealMultiVector
   let a = RealMultiVector::new(data_a,metric ).unwrap();

Usage

Add this crate to your Cargo.toml.

deep_causality_multivector = { version = "0.1" }

Basic Operations

use deep_causality_multivector::{CausalMultiVector, Metric};

fn main() {
    // Create two vectors in 2D Euclidean space

    let mut data_a = vec![0.0; 4];
    data_a[1] = 1.0; // 1.0 * e1
    let a = CausalMultiVector::new_euclidean(data_a).unwrap();

    let mut data_b = vec![0.0; 4];
    data_b[2] = 1.0; // 1.0 * e2
    let b = CausalMultiVector::new_euclidean(data_b).unwrap();

    // Geometric Product: e1 * e2 = e12
    let product = a * b;
    println!("e1 * e2 = e12 coefficient: {}", product.get(3).unwrap());
}

Using Aliases (e.g., PGA)

use deep_causality_multivector::PGA3DMultiVector;

fn main() {
    // Create a point in 3D PGA (Dual representation)
    let point = PGA3DMultiVector::new_point(1.0, 2.0, 3.0);

    // Create a translator (Motor)
    let translator = PGA3DMultiVector::translator(2.0, 0.0, 0.0); // Shift x by 2

    // Apply transformation: P' = T * P * ~T
    let t_rev = translator.reversion();
    let transformed = translator.clone() * point * t_rev;

    println!("Transformed X: {}", transformed.get(13).unwrap()); // e032 component
}

Higher-Kinded Types (HKT)

This crate implements HKT traits from deep_causality_haft.

• Functor: Map a function over the coefficients, leaving the metric alone.
• Pure and Applicative: Lift a value into $Cl(0)$ and broadcast a function over the coefficients.
• Foldable: Reduce the coefficients to a summary value.
• CoMonad: Read every coefficient in the context of the whole multivector.

use deep_causality_haft::{Applicative, Functor, Pure};
use deep_causality_multivector::{CausalMultiVector, CausalMultiVectorWitness, Metric};

fn main() {
    // Functor: map over the coefficients.
    let v = CausalMultiVector::new(vec![1.0, 2.0, 3.0, 4.0], Metric::Euclidean(2)).unwrap();
    let scaled = CausalMultiVectorWitness::fmap(v.clone(), |x| x * 2.0);
    assert_eq!(scaled.data(), &vec![2.0, 4.0, 6.0, 8.0]);

    // Applicative: broadcast one function across every coefficient.
    let pure_fn = CausalMultiVectorWitness::pure(|x: f64| x + 10.0);
    let shifted = CausalMultiVectorWitness::apply(pure_fn, v);
    assert_eq!(shifted.data(), &vec![11.0, 12.0, 13.0, 14.0]);
}

Why there is no Monad

A CausalMultiVector holds exactly $2^N$ coefficients, where $N$ comes from its Metric, so the metric is not decoration: it fixes the length. Monad::bind receives one metric from its input and another from every f(a), and the two identity laws demand opposite choices. Left identity, bind(pure(a), f) == f(a), needs the metric taken from f's result, because pure(a) carries only Euclidean(0). Right identity, bind(m, pure) == m, needs the metric taken from the input, for the same reason. No metric choice satisfies both, so the instance is left out rather than shipped broken.

Pure stays. pure(x) names $Cl(0)$, the one algebra reachable without inventing geometry, and its single coefficient is exactly $2^0$, so the value it builds is well formed.

An operation that changes the algebra, such as a tensor product, therefore states its target metric itself. The hkt_multivector.rs example writes one out.

Examples

Benchmarks

Performance measured on Apple M3 Max.

Contribution

Contributions are welcomed especially related to documentation, example code, and fixes. If unsure where to start, just open an issue and ask.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in deep_causality by you, shall be licensed under the MIT licence, without any additional terms or conditions.

Licence

This project is licensed under the MIT license.

Security

For details about security, please read the security policy.