doc(deep_causality_tensor): Added example code and updated Readme for Einstein Sum.

Signed-off-by: Marvin Hansen <[email protected]>

Author: marvin-hansen

deep_causality_tensor/Cargo.toml

@@ -27,6 +27,10 @@ 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"

deep_causality_tensor/README.md

@@ -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/examples/ein_sum_causal_tensor.rs

@@ -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/src/types/causal_tensor/op_tensor_ein_sum/ein_sum_impl.rs

@@ -20,7 +20,8 @@ where
     /// # Arguments
     ///
     /// * `children` - A slice of `EinSumAST<T>` representing the children nodes of an AST operation.
-    ///                Expected to contain exactly two elements, each resolving to a `CausalTensor<T>`.
+    ///
+    /// Expected to contain exactly two elements, each resolving to a `CausalTensor<T>`.
     ///
     /// # Returns
     ///
@@ -58,7 +59,8 @@ where
     /// # Arguments
     ///
     /// * `children` - A slice of `EinSumAST<T>` representing the children nodes of an AST operation.
-    ///                Expected to contain exactly one element, resolving to a `CausalTensor<T>`.
+    ///
+    /// Expected to contain exactly one element, resolving to a `CausalTensor<T>`.
     ///
     /// # Returns
     ///