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.

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.