# 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`
| **Complex Quaternions** | $Cl(2, 0)$ | `new_complex_pauli` (Alias for `new_complex_clifford_2`) |
| **Quaternion Operator** | $Cl(0, 4)$ | `new_quaternion_operator` (Alias for `new_complex_clifford_4`) |
| **Octonion Operator** | $Cl(0, 6)$ | `new_octonion_operator` (Alias for `new_complex_clifford_6`) |
| **Dixon Left Mult. Alg.** | $Cl(0, 8)$ | `new_dixon_algebra_left` (Alias for `new_complex_clifford_8`) |
| **Grand Unified Algebra** | $Cl(0, 10)$ | `new_gut_algebra` (Alias for `new_complex_clifford_10`) |
### 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`
| **Euclidean Vectors** | $Cl(N, 0)$ | N-dim Euclidean | `RealMultiVector::new_euclidean` |
| **Complex Numbers** | $Cl(0, 1)$ | | `RealMultiVector::new_complex_number` |
| **Split Complex Numbers** | $Cl(1, 0)$ | | `RealMultiVector::new_split_complex` |
| **Quaternions** | $Cl(0, 2)$ | | `RealMultiVector::new_quaternion` |
| **Split Quaternions** | $Cl(2, 0)$ | | `RealMultiVector::new_split_quaternion` |
| **Pauli (APS)** | $Cl(3, 0)$ | | `RealMultiVector::new_aps_vector` |
| **Spacetime (STA)** | $Cl(1, 3)$ | Physics (+ - - -) | `RealMultiVector::new_spacetime_algebra_1_3` |
| **Spacetime (STA)** | $Cl(3, 1)$ | Math/GR (- + + +) | `RealMultiVector::new_spacetime_algebra_3_1` |
| **Conformal (CGA)** | $Cl(4, 1)$ | | `RealMultiVector::new_cga_vector` |
### Quantum State Vector (HilbertState)
* **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)
| **Quantum State Vector** | $Cl(0, 10)$ | `HilbertState::new_spin10` (enforces $Cl(0,10)$) |
| **Generic Qubit/State** | Arbitrary | `HilbertState::new` (allows any Metric) |
### 3D Projective Geometric Algebra
Type: PGA3DMultiVector
| **PGA 3D** | $Cl(3, 0, 1)$ | `PGA3DMultiVector::new_point` |
## 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`.
```toml
deep_causality_multivector = { version = "0.1" }
```
### Basic Operations
```rust
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)
```rust
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.
```rust
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.
```rust
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
| `basic_multivector.rs` | `CausalMultiVector` (`Euclidean(2)`) | Demonstrates basic geometric algebra operations (geometric, outer, inner product, inverse) in a 2D Euclidean space. |
| `clifford_mhd_mulitvector.rs` | `CausalMultiVector` (`Euclidean(3)`, `Minkowski(4)`) | Simulates Lorentz force in plasma fusio using both Euclidean and Minkowski metrics for metric-agnostic calculations. |
| `dixon_multivector.rs` | `DixonAlgebra` (Cl_C(6)) | Demonstrates operations within the Dixon Algebra, including basis vector construction, geometric products, and complex scalar multiplication. |
| `hkt_multivector.rs` | `CausalMultiVector` (`Euclidean`) | Demonstrates Higher-Kinded Types (HKT) including Functor, Applicative, and Monad implemented for `CausalMultiVector`. |
| `pga3d_multivector.rs` | `PGA3DMultiVector` (3D PGA) | Demonstrates 3D Projective Geometric Algebra (PGA) by creating a point, a translator (motor), and applying transformations. |
## Benchmarks
Performance measured on Apple M3 Max.
| **Geometric Product** | Euclidean 2D | ~89.6 ns |
| **Geometric Product** | PGA 3D | ~87.5 ns |
| **Addition** | Euclidean 3D | ~39.1 ns |
| **Reversion** | PGA 3D | ~37.3 ns |
## License
This project is licensed under the [MIT license](LICENSE).
## Security
For details about security, please read
the [security policy](https://github.com/deepcausality-rs/deep_causality/blob/main/SECURITY.md).
## Author
* [Marvin Hansen](https://github.com/marvin-hansen).
* Github GPG key ID: 369D5A0B210D39BC
* GPG Fingerprint: 4B18 F7B2 04B9 7A72 967E 663E 369D 5A0B 210D 39BC