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, Applicative, and Monad (via deep_causality_haft) for advanced functional patterns.
  • Monad::bind implements the Tensor Product of algebras.

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 matrix
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 coefficients.
• Applicative: Lift values and apply functions.
• Monad: Tensor product of algebras.

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

fn main() {
    println!("=== Higher-Kinded Types (HKT) with CausalMultiVector ===");

    // 1. Functor: Mapping over coefficients
    println!("\n--- Functor (Map) ---");
    let v = CausalMultiVector::new_euclidean(vec![1.0, 2.0, 3.0, 4.0]).unwrap();
    println!("Original Vector: {:?}", v.data);

    // Scale by 2.0 using fmap
    let scaled = CausalMultiVectorWitness::fmap(v.clone(), |x| x * 2.0);
    println!("Scaled Vector (x2): {:?}", scaled.data);
    assert_eq!(scaled.data, vec![2.0, 4.0, 6.0, 8.0]);

    // 2. Applicative: Broadcasting a function
    println!("\n--- Applicative (Apply/Broadcast) ---");
    // Create a "pure" function wrapped in a scalar multivector
    let pure_fn = CausalMultiVectorWitness::pure(|x: f64| x + 10.0);

    // Apply it to our vector
    let shifted = CausalMultiVectorWitness::apply(pure_fn, v.clone());
    println!("Shifted Vector (+10): {:?}", shifted.data);
    assert_eq!(shifted.data, vec![11.0, 12.0, 13.0, 14.0]);

    // 3. Monad: Tensor Product via Bind    
    //...
    // See examples/hkt_usage.rs for full demonstration
}

Quantum Operations

This crate provides QuantumGates (for creating common unitary operators) and QuantumOps (for fundamental quantum mechanical operations) via the HilbertState type.

use deep_causality_multivector::{HilbertState, QuantumGates, QuantumOps};
use deep_causality_num::Complex64;

fn main() {
    println!("--- Quantum Operations Example ---");

    // 1. Create an initial state (analogous to |0>)
    let zero_state = HilbertState::gate_identity();
    println!("Initial state (scalar part): {:.4?}", zero_state.mv().data()[0]);

    // 2. Apply a Hadamard Gate to create a superposition state
    let h_gate = HilbertState::gate_hadamard();
    let plus_state = HilbertState::from(
        h_gate.into_inner().geometric_product(zero_state.as_inner())
    );
    println!("Superposition state (scalar part): {:.4?}", plus_state.mv().data()[0]);
    // Note: Due to the Cl(0,10) mapping, this scalar might be 0,
    // actual components will be in e1 and e12 terms of the multivector.

    // 3. Calculate inner product (e.g., <+|+>)
    let norm_squared = plus_state.bracket(&plus_state);
    println!("Inner product <+|+>: {:.4?} (Should ideally be 1.0 for normalized state)", norm_squared);
    // Note: For certain GA mappings, this might not be 1.0 directly
    // for states that are not minimal left ideals.

    // 4. Normalize the initial state
    let unnormalized_scalar = Complex64::new(2.0, 0.0);
    let mut unnormalized_data = vec![Complex64::zero(); 1024]; // Size for Cl(0,10)
    unnormalized_data[0] = unnormalized_scalar;
    let unnormalized_state = HilbertState::new_spin10(unnormalized_data).unwrap();
    println!("Unnormalized state (scalar part): {:.4?}", unnormalized_state.mv().data()[0]);

    let normalized_state = unnormalized_state.normalize();
    println!("Normalized state (scalar part): {:.4?}", normalized_state.mv().data()[0]);
    println!("Inner product of normalized state with itself: {:.4?}", normalized_state.bracket(&normalized_state));
}

Examples

Benchmarks

Performance measured on Apple M3 Max.

License

This project is licensed under the MIT license.

Security

For details about security, please read the security policy.

Author

• Marvin Hansen.
• Github GPG key ID: 369D5A0B210D39BC
• GPG Fingerprint: 4B18 F7B2 04B9 7A72 967E 663E 369D 5A0B 210D 39BC