Merge pull request #375 from marvin-hansen/main

feat(deep_causality_tensor): Implement and document Einstein Sum   Convention

Author: marvin-hansen

.bazelignore

@@ -1,5 +1,6 @@
 .cargo
 .gemini
+.gemini_security
 .git
 .github
 .specify

.bazelversion

@@ -1 +1 @@
-8.4.1
+8.4.2

Cargo.lock

@@ -11,6 +11,7 @@ rust_library(
     ],
     visibility = ["//visibility:public"],
     deps = [
+        "//deep_causality_ast",
         "//deep_causality_haft",
         "//deep_causality_num",
     ],

MODULE.bazel.lock

@@ -27,10 +27,17 @@ path = "examples/basic_causal_tensor.rs"
 name = "effect_system_causal_tensor"
 path = "examples/effect_system_causal_tensor.rs"
 
+[[example]]
+name = "ein_sum_causal_tensor"
+path = "examples/ein_sum_causal_tensor.rs"
+
 [[example]]
 name = "functor_causal_tensor"
 path = "examples/functor_causal_tensor.rs"
 
+[dependencies.deep_causality_ast]
+path = "../deep_causality_ast"
+version = "0.1"
 
 [dependencies.deep_causality_haft]
 path = "../deep_causality_haft"

deep_causality_tensor/BUILD.bazel

@@ -17,6 +17,31 @@ tasks.
 * [Examples](../deep_causality_tensor/examples)
 * [Test](../deep_causality_tensor/tests)
 
+## Examples
+
+To run the examples, use `cargo run --example <example_name>`.
+
+*   **Applicative Causal Tensor**
+    ```bash
+    cargo run --example applicative_causal_tensor
+    ```
+*   **Basic Causal Tensor**
+    ```bash
+    cargo run --example causal_tensor
+    ```
+*   **Effect System Causal Tensor**
+    ```bash
+    cargo run --example effect_system_causal_tensor
+    ```
+*   **Einstein Summation Causal Tensor**
+    ```bash
+    cargo run --example ein_sum_causal_tensor
+    ```
+*   **Functor Causal Tensor**
+    ```bash
+    cargo run --example functor_causal_tensor
+    ```
+
 ## Usage
 
 `CausalTensor` is straightforward to use. You create it from a flat vector of data and a vector defining its shape.
@@ -62,6 +87,51 @@ fn main() {
 }
 ```
 
+## Einstein Sum (ein_sum)
+
+The `ein_sum` function provides a powerful and flexible way to perform various tensor operations, including matrix multiplication, dot products, and more, by constructing an Abstract Syntax Tree (AST) of operations.
+
+```rust
+use deep_causality_tensor::CausalTensor;
+use deep_causality_tensor::types::causal_tensor::op_tensor_ein_sum::EinSumOp;
+
+fn main() {
+    // Example: Matrix Multiplication using ein_sum
+    let lhs_data = vec![1.0, 2.0, 3.0, 4.0];
+    let lhs_tensor = CausalTensor::new(lhs_data, vec![2, 2]).unwrap();
+
+    let rhs_data = vec![5.0, 6.0, 7.0, 8.0];
+    let rhs_tensor = CausalTensor::new(rhs_data, vec![2, 2]).unwrap();
+
+    // Construct the AST for matrix multiplication
+    let mat_mul_ast = EinSumOp::mat_mul(lhs_tensor, rhs_tensor);
+
+    // Execute the Einstein summation
+    let result = CausalTensor::ein_sum(&mat_mul_ast).unwrap();
+
+    println!("Result of Matrix Multiplication:\n{:?}", result);
+    // Expected: CausalTensor { data: [19.0, 22.0, 43.0, 50.0], shape: [2, 2], strides: [2, 1] }
+    
+     // Example: Dot Product
+    let vec1_data = vec![1.0, 2.0, 3.0];
+    let vec1_shape = vec![3];
+    let vec1_tensor = CausalTensor::new(vec1_data, vec1_shape).unwrap();
+
+    let vec2_data = vec![4.0, 5.0, 6.0];
+    let vec2_shape = vec![3];
+    let vec2_tensor = CausalTensor::new(vec2_data, vec2_shape).unwrap();
+    
+    // Execute the Einstein summation for dot product 
+    let result_dot_prod = CausalTensor::ein_sum(&EinSumOp::dot_prod(
+        vec1_tensor.clone(),
+        vec2_tensor.clone(),
+    ))
+    .unwrap();
+    println!("Result of Dot Product:\n{:?}", result_dot_prod);
+}
+```
+
+
 ## Functional Composition 
 
 Causal Tensor implements a Higher Kinded Type via the `deep_causality_haft` crate as Witness Type. When imported, the CausalTensorWitness type allows monadic composition and abstract type programming. For example, one can write generic functions that uniformly process tensors and other types:

deep_causality_tensor/Cargo.toml

@@ -0,0 +1,118 @@
+/*
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
+ */
+use deep_causality_tensor::{CausalTensor, EinSumOp};
+
+fn main() {
+    // Example 1: Matrix Multiplication
+    println!("--- Example 1: Matrix Multiplication ---");
+    let lhs_data = vec![1.0, 2.0, 3.0, 4.0];
+    let lhs_shape = vec![2, 2];
+    let lhs_tensor = CausalTensor::new(lhs_data, lhs_shape).unwrap();
+
+    let rhs_data = vec![5.0, 6.0, 7.0, 8.0];
+    let rhs_shape = vec![2, 2];
+    let rhs_tensor = CausalTensor::new(rhs_data, rhs_shape).unwrap();
+
+    println!("LHS Tensor:\n{:?}", lhs_tensor);
+    println!("RHS Tensor:\n{:?}", rhs_tensor);
+
+    let result_mat_mul =
+        CausalTensor::ein_sum(&EinSumOp::mat_mul(lhs_tensor.clone(), rhs_tensor.clone())).unwrap();
+    println!("Result of Matrix Multiplication:\n{:?}", result_mat_mul);
+    let expected_mat_mul = CausalTensor::new(vec![19.0, 22.0, 43.0, 50.0], vec![2, 2]).unwrap();
+    assert_eq!(result_mat_mul, expected_mat_mul);
+
+    // Example 2: Dot Product
+    println!("\n--- Example 2: Dot Product ---");
+    let vec1_data = vec![1.0, 2.0, 3.0];
+    let vec1_shape = vec![3];
+    let vec1_tensor = CausalTensor::new(vec1_data, vec1_shape).unwrap();
+
+    let vec2_data = vec![4.0, 5.0, 6.0];
+    let vec2_shape = vec![3];
+    let vec2_tensor = CausalTensor::new(vec2_data, vec2_shape).unwrap();
+
+    println!("Vector 1:\n{:?}", vec1_tensor);
+    println!("Vector 2:\n{:?}", vec2_tensor);
+
+    let result_dot_prod = CausalTensor::ein_sum(&EinSumOp::dot_prod(
+        vec1_tensor.clone(),
+        vec2_tensor.clone(),
+    ))
+    .unwrap();
+    println!("Result of Dot Product:\n{:?}", result_dot_prod);
+    let expected_dot_prod = CausalTensor::new(vec![32.0], vec![]).unwrap();
+    assert_eq!(result_dot_prod, expected_dot_prod);
+
+    // Example 3: Trace
+    println!("\n--- Example 3: Trace ---");
+    let trace_data = vec![1.0, 2.0, 3.0, 4.0];
+    let trace_shape = vec![2, 2];
+    let trace_tensor = CausalTensor::new(trace_data, trace_shape).unwrap();
+
+    println!("Tensor for Trace:\n{:?}", trace_tensor);
+    let result_trace = CausalTensor::ein_sum(&EinSumOp::trace(trace_tensor.clone(), 0, 1)).unwrap();
+    println!("Result of Trace (axes 0, 1):\n{:?}", result_trace);
+    let expected_trace = CausalTensor::new(vec![5.0], vec![]).unwrap();
+    assert_eq!(result_trace, expected_trace);
+
+    // Example 4: Element-wise Product
+    println!("\n--- Example 4: Element-wise Product ---");
+    let ew_lhs_data = vec![1.0, 2.0, 3.0];
+    let ew_lhs_shape = vec![3];
+    let ew_lhs_tensor = CausalTensor::new(ew_lhs_data, ew_lhs_shape).unwrap();
+
+    let ew_rhs_data = vec![4.0, 5.0, 6.0];
+    let ew_rhs_shape = vec![3];
+    let ew_rhs_tensor = CausalTensor::new(ew_rhs_data, ew_rhs_shape).unwrap();
+
+    println!("LHS Tensor for Element-wise Product:\n{:?}", ew_lhs_tensor);
+    println!("RHS Tensor for Element-wise Product:\n{:?}", ew_rhs_tensor);
+
+    let result_ew_prod = CausalTensor::ein_sum(&EinSumOp::element_wise_product(
+        ew_lhs_tensor.clone(),
+        ew_rhs_tensor.clone(),
+    ))
+    .unwrap();
+    println!("Result of Element-wise Product:\n{:?}", result_ew_prod);
+    let expected_ew_prod = CausalTensor::new(vec![4.0, 10.0, 18.0], vec![3]).unwrap();
+    assert_eq!(result_ew_prod, expected_ew_prod);
+
+    // Example 5: Batch Matrix Multiplication
+    println!("\n--- Example 5: Batch Matrix Multiplication ---");
+    // Batch of two 2x2 matrices
+    let bmm_lhs_data = vec![
+        1.0, 2.0, 3.0, 4.0, // First 2x2 matrix
+        5.0, 6.0, 7.0, 8.0, // Second 2x2 matrix
+    ];
+    let bmm_lhs_shape = vec![2, 2, 2]; // 2 batches, 2 rows, 2 cols
+    let bmm_lhs_tensor = CausalTensor::new(bmm_lhs_data, bmm_lhs_shape).unwrap();
+
+    let bmm_rhs_data = vec![
+        9.0, 10.0, 11.0, 12.0, // First 2x2 matrix
+        13.0, 14.0, 15.0, 16.0, // Second 2x2 matrix
+    ];
+    let bmm_rhs_shape = vec![2, 2, 2]; // 2 batches, 2 rows, 2 cols
+    let bmm_rhs_tensor = CausalTensor::new(bmm_rhs_data, bmm_rhs_shape).unwrap();
+
+    println!("LHS Tensor for Batch MatMul:\n{:?}", bmm_lhs_tensor);
+    println!("RHS Tensor for Batch MatMul:\n{:?}", bmm_rhs_tensor);
+
+    let result_bmm = CausalTensor::ein_sum(&EinSumOp::batch_mat_mul(
+        bmm_lhs_tensor.clone(),
+        bmm_rhs_tensor.clone(),
+    ))
+    .unwrap();
+    println!("Result of Batch Matrix Multiplication:\n{:?}", result_bmm);
+    let expected_bmm = CausalTensor::new(
+        vec![
+            31.0, 34.0, 71.0, 78.0, // First 2x2 matrix result
+            155.0, 166.0, 211.0, 226.0, // Second 2x2 matrix result
+        ],
+        vec![2, 2, 2],
+    )
+    .unwrap();
+    assert_eq!(result_bmm, expected_bmm);
+}

deep_causality_tensor/README.md

@@ -2,6 +2,7 @@
  * SPDX-License-Identifier: MIT
  * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
  */
+use crate::EinSumValidationError;
 use std::error::Error;
 
 /// Errors that can occur during tensor operations.
@@ -15,6 +16,8 @@ pub enum CausalTensorError {
     InvalidOperation,
     UnorderableValue,
     InvalidParameter(String),
+    /// Encapsulates errors specific to EinSum AST validation and execution.
+    EinSumError(EinSumValidationError),
 }
 
 impl Error for CausalTensorError {}
@@ -44,6 +47,9 @@ impl std::fmt::Display for CausalTensorError {
             CausalTensorError::DivisionByZero => {
                 write!(f, "CausalTensorError: Division by zero error")
             }
+            CausalTensorError::EinSumError(e) => {
+                write!(f, "CausalTensorError: EinSumError: {}", e)
+            }
         }
     }
 }

deep_causality_tensor/examples/ein_sum_causal_tensor.rs

@@ -0,0 +1,60 @@
+/*
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
+ */
+use std::error::Error;
+
+/// Specific errors that can occur during EinSum AST validation or execution.
+#[derive(Debug, Clone, PartialOrd, PartialEq)]
+pub enum EinSumValidationError {
+    /// Indicates an incorrect number of child nodes for an AST operation.
+    InvalidNumberOfChildren { expected: usize, found: usize },
+    /// Indicates an issue with the specified axes for an operation (e.g., out of bounds, duplicate).
+    InvalidAxesSpecification { message: String },
+    /// Indicates an operation that is not yet implemented or is used in an unsupported context.
+    UnsupportedOperation { operation: String },
+    /// Indicates a mismatch in tensor shapes that prevents an operation from proceeding.
+    ShapeMismatch { message: String },
+    /// Indicates that a tensor has an unexpected rank for a given operation.
+    RankMismatch { expected: usize, found: usize },
+}
+
+impl std::fmt::Display for EinSumValidationError {
+    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+        match self {
+            EinSumValidationError::InvalidNumberOfChildren { expected, found } => {
+                write!(
+                    f,
+                    "EinSumValidationError: Invalid number of children. Expected {}, found {}",
+                    expected, found
+                )
+            }
+            EinSumValidationError::InvalidAxesSpecification { message } => {
+                write!(
+                    f,
+                    "EinSumValidationError: Invalid axes specification: {}",
+                    message
+                )
+            }
+            EinSumValidationError::UnsupportedOperation { operation } => {
+                write!(
+                    f,
+                    "EinSumValidationError: Unsupported operation: {}",
+                    operation
+                )
+            }
+            EinSumValidationError::ShapeMismatch { message } => {
+                write!(f, "EinSumValidationError: Shape mismatch: {}", message)
+            }
+            EinSumValidationError::RankMismatch { expected, found } => {
+                write!(
+                    f,
+                    "EinSumValidationError: Rank mismatch. Expected {}, found {}",
+                    expected, found
+                )
+            }
+        }
+    }
+}
+
+impl Error for EinSumValidationError {}