adds benchmarking tests for tensor transpose and gemm along with documentation

Author: erdalmutlu

docs/benchmarking_docs/gemm_benchmarks.rst

@@ -0,0 +1,153 @@
+.. _test_gemm_benchmark:
+
+=======================
+GEMM Benchmark Test
+=======================
+
+Overview
+========
+
+Test_GEMM measures the performance of General Matrix Multiply (GEMM) operations using the TAMM framework. It reads test configurations from CSV files and reports timing, GFLOPS, and throughput metrics for both GPU and CPU execution.
+
+Basic Usage
+-----------
+
+.. code-block:: bash
+
+   # Run with default settings
+   mpirun -n 2 ./Test_GEMM test_cases.csv
+   
+   # Specify custom iterations
+   mpirun -n 2 ./Test_GEMM test_cases.csv 50
+
+Command Line Arguments
+======================
+
+.. code-block:: bash
+
+   mpirun -n 2 ./Test_GEMM <csv_file> [iterations]
+
+**Required Arguments:**
+
+* ``csv_file``: Path to CSV file containing GEMM test case definitions
+
+**Optional Arguments:**
+
+* ``iterations``: Number of benchmark runs per test case (default: 100)
+
+**Examples:**
+
+.. code-block:: bash
+
+   # Test with default 100 iterations
+   mpirun -n 2 ./Test_GEMM gemm_cases.csv
+   
+   # Test with 50 iterations
+   mpirun -n 2 ./Test_GEMM gemm_cases.csv 50
+   
+   # Test with 200 iterations
+   mpirun -n 2 ./Test_GEMM gemm_cases.csv 200
+
+Input File Format
+=================
+
+The program expects a CSV file with GEMM configurations using the following 7-column format:
+
+CSV Header
+----------
+
+.. code-block:: text
+
+   contraction_size,output_a_size,output_b_size,total_output_size,batch_size,reduction_a_size,reduction_b_size
+
+Column Definitions
+------------------
+
+* **contraction_size**: Size of the contraction dimension (K in GEMM)
+* **output_a_size**: Output size for matrix A (M dimension)
+* **output_b_size**: Output size for matrix B (N dimension)
+* **total_output_size**: Total output matrix size (M×N)
+* **batch_size**: Batch size for batched operations
+* **reduction_a_size**: Reduction size for matrix A operations
+* **reduction_b_size**: Reduction size for matrix B operations
+
+Sample Data
+-----------
+
+.. code-block:: text
+
+   contraction_size,output_a_size,output_b_size,total_output_size,batch_size,reduction_a_size,reduction_b_size
+   1,2655,526,1396530,1,1,1
+   1,2655,1000,2655000,1,1,1
+   45,59,45,2655,1,1,1
+   45,59,59,3481,1,1,1
+   59,45,45,2025,1,1,1
+   67,75,67,5025,1,1,1
+
+Understanding the Format
+========================
+
+GEMM Dimensions
+---------------
+
+* **M (output_a_size)**: Number of rows in matrix A and result matrix C
+* **N (output_b_size)**: Number of columns in matrix B and result matrix C
+* **K (contraction_size)**: Shared dimension between matrices A and B
+* **B (batch_size)**: Number of matrices in batched operations
+
+Matrix Operation
+----------------
+
+The GEMM operation computes: **C = α × A × B + β × C**
+
+* Matrix A dimensions: M × K
+* Matrix B dimensions: K × N  
+* Matrix C dimensions: M × N
+* All dimensions must be positive integers
+
+Batch Operations
+----------------
+
+* **batch_size**: Defines number of independent GEMM operations
+* **reduction_a_size**: Additional reduction factor for matrix A
+* **reduction_b_size**: Additional reduction factor for matrix B
+* Example: batch_size=4 performs 4 separate GEMM operations
+
+Sample Test Cases
+=================
+
+.. code-block:: text
+
+   contraction_size,output_a_size,output_b_size,total_output_size,batch_size,reduction_a_size,reduction_b_size
+   1,2655,526,1396530,1,1,1
+   1,2655,1000,2655000,1,1,1
+   1,5025,526,2643150,1,1,1
+   45,59,45,2655,1,1,1
+   45,59,59,3481,1,1,1
+   59,45,45,2025,1,1,1
+   67,75,67,5025,1,1,1
+   526,1,1,1,1,1,1
+   526,2025,1,2025,1,1,1
+   526,2025,2025,4100625,1,1,1
+
+Sample Output
+-------------
+
+.. code-block:: text
+
+   Loaded 10 GEMM test cases (double precision)
+   
+   Testing: GEMM_double_59x45x45_B1_AR1_BR1
+     Matrix dimensions: A(59x45) × B(45x45) = C(59x45)
+     Batch size: 1
+     Reduction dimensions: AR=1, BR=1
+     Data type: double (8 bytes per element)
+     Buffer sizes: A=2655, B=2025, C=2655
+     Allocating buffers...
+     Running 100 timing iterations...
+     Total FLOPs: 2.385e+05
+     Data size: 0.056 MB
+     Iterations: 100
+     Average time: 0.045123 ms
+     Performance: 5.284 GFLOPS
+     Throughput: 2.484 GB/s

docs/benchmarking_docs/transpose_benchmarks.rst

@@ -0,0 +1,138 @@
+.. _test_tensor_transpose:
+
+===============================
+Tensor Transpose Benchmark Test
+===============================
+
+Overview
+========
+
+Test_Tensor_Transpose measures the performance of tensor transpose operations in. It reads test configurations from CSV files and reports timing and throughput metrics for both GPU and CPU execution.
+
+Basic Usage
+-----------
+
+.. code-block:: bash
+
+   # Run with default settings
+   mpirun -n 2 ./transpose_benchmark test_cases.csv
+
+   # Specify iterations and data type
+   mpirun -n 2 ./transpose_benchmark test_cases.csv 50 float
+
+Command Line Arguments
+======================
+
+.. code-block:: bash
+
+   mpirun -n <processes> ./transpose_benchmark <csv_file> [iterations] [data_type]
+
+**Required Arguments:**
+
+* ``csv_file``: Path to CSV file containing test case definitions
+
+**Optional Arguments:**
+
+* ``iterations``: Number of benchmark runs per test case (default: 100)
+* ``data_type``: Data precision - ``float``, ``double``, or ``all`` (default: ``double``)
+
+**Examples:**
+
+.. code-block:: bash
+
+   # Test double precision with 100 iterations
+   mpirun -n 2 ./transpose_benchmark cases.csv
+
+   # Test single precision with 50 iterations  
+   mpirun -n 2 ./transpose_benchmark cases.csv 50 float
+
+   # Test both precisions with 200 iterations
+   mpirun -n 2 ./transpose_benchmark cases.csv 200 all
+
+Input File Format
+=================
+
+The program expects a CSV file with tensor transpose configurations using the following 9-column format:
+
+CSV Header
+----------
+
+.. code-block:: text
+
+   block_size_dim_0,block_size_dim_1,block_size_dim_2,block_size_dim_3,permutation_map_idx_0,permutation_map_idx_1,permutation_map_idx_2,permutation_map_idx_3,original_transpose_string
+
+Column Definitions
+------------------
+
+* **block_size_dim_0 to block_size_dim_3**: Tensor dimension sizes (use ``1`` for unused dimensions)
+* **permutation_map_idx_0 to permutation_map_idx_3**: Target position for each dimension (use ``-1`` for unused positions)
+* **original_transpose_string**: Mathematical description of the transpose operation
+
+Sample Data
+-----------
+
+.. code-block:: text
+
+   block_size_dim_0,block_size_dim_1,block_size_dim_2,block_size_dim_3,permutation_map_idx_0,permutation_map_idx_1,permutation_map_idx_2,permutation_map_idx_3,original_transpose_string
+   45,45,1,1,1,0,-1,-1,C( 0 1 ) <- C'( 1 0 )
+   100,45,1,1,1,0,-1,-1,C( 0 1 ) <- C'( 1 0 )
+   75,67,2,1,0,2,1,-1,B( 2 1 3 ) -> B'( 2 3 1 )
+   75,67,3,1,1,0,2,-1,C( 0 1 2 ) <- C'( 1 0 2 )
+
+Understanding the Format
+========================
+
+Dimension Specification
+-----------------------
+
+* Valid dimensions must be > 1
+* Use ``1`` for unused/singleton dimensions
+* Example: ``75,67,4,1`` represents a 3D tensor of size 75×67×4
+
+Permutation Mapping
+-------------------
+
+* Each index specifies where the corresponding input dimension goes in the output
+* Use ``-1`` for unused positions
+* Example: ``1,0,-1,-1`` means dimension 0 → position 1, dimension 1 → position 0
+
+Transpose String Notation
+-------------------------
+
+The mathematical notation describes the operation:
+
+* ``C( 0 1 ) <- C'( 1 0 )``: Matrix transpose (swap dimensions 0 and 1)
+* ``B( 2 1 3 ) -> B'( 2 3 1 )``: Cyclic permutation of 3D tensor
+* ``C( 0 1 2 ) <- C'( 1 0 2 )``: Transpose first two dimensions, keep third unchanged
+
+Sample Test Cases
+=================
+
+.. code-block:: text
+
+   block_size_dim_0,block_size_dim_1,block_size_dim_2,block_size_dim_3,permutation_map_idx_0,permutation_map_idx_1,permutation_map_idx_2,permutation_map_idx_3,original_transpose_string
+   45,45,1,1,1,0,-1,-1,C( 0 1 ) <- C'( 1 0 )
+   100,45,1,1,1,0,-1,-1,C( 0 1 ) <- C'( 1 0 )
+   55,45,1,1,1,0,-1,-1,C( 0 1 ) <- C'( 1 0 )
+   75,67,2,1,0,2,1,-1,B( 2 1 3 ) -> B'( 2 3 1 )
+   75,67,3,1,1,0,2,-1,C( 0 1 2 ) <- C'( 1 0 2 )
+   75,67,4,1,1,2,0,-1,B( 0 2 3 ) -> B'( 2 3 0 )
+   75,67,5,1,2,0,1,-1,B( 1 3 4 ) -> B'( 4 1 3 )
+
+Sample Output
+-------------
+
+.. code-block:: text
+
+   ========== TESTING WITH TYPE: d ==========
+   === GPU TESTS ===
+   Testing (d): C( 0 1 ) <- C'( 1 0 )
+     Dimensions: [45,45] -> [45,45]
+     Permutation: [0,1] -> [1,0]
+     Elements: 2025
+     Data size: 0.015488 MB
+     Element size: 8 bytes
+     Iterations: 100
+     Average time: 0.032145 ms
+     Throughput: 0.964 GB/s
+     Hardware: GPU

src/tamm/kernels/multiply.hpp

@@ -39,6 +39,18 @@ void copy_data_to_gpu(ExecutionHW hw, gpuStream_t& thandle, const T2* ainter_buf
 #endif
 }
 
+template<typename T>
+void copy_data_to_gpu(ExecutionHW hw, gpuStream_t& thandle, const T* ainter_buf, size_t asize,
+                      T* ainter_buf_dev) {
+  if(hw == ExecutionHW::CPU) return;
+
+  auto&      oprof = tamm::OpProfiler::instance();
+  TimerGuard tg_copy{&oprof.multOpCopyTime};
+#if defined(USE_CUDA) || defined(USE_HIP) || defined(USE_DPCPP)
+  gpuMemcpyAsync<T>(ainter_buf_dev, ainter_buf, asize, gpuMemcpyHostToDevice, thandle);
+#endif
+}
+
 template<typename T, typename T1, typename T2, typename T3>
 void gemm_wrapper(ExecutionHW hw, gpuStream_t& thandle, int AR, int BR, int B, int M, int N, int K,
                   T alpha, T beta, const T2* ainter_buf, const T2* ainter_buf_dev,
@@ -209,6 +221,42 @@ void transpose_output(ExecutionHW hw, gpuStream_t& thandle, bool gpu_trans, T1*
   assign<T1>(cbuf, cdims, clabels, T1{1}, cinter_buf, cinter_dims, cinter_labels, is_assign);
 }
 
+template<typename T>
+bool transpose_tensor(ExecutionHW hw, gpuStream_t& thandle, T* output_buf,
+                      const SizeVec& output_dims, const IntLabelVec& output_labels,
+                      const T* input_buf, size_t input_size, const SizeVec& input_dims,
+                      const IntLabelVec& input_labels, T*& output_buf_dev) {
+  bool gpu_trans = false;
+
+#if defined(USE_CUDA) || defined(USE_HIP) || defined(USE_DPCPP)
+  if(hw == ExecutionHW::GPU) {
+    gpu_trans = true;
+
+    // Allocate temporary device buffer for input
+    T* input_buf_dev{nullptr};
+    allocate_device_buffers(hw, input_buf_dev, input_size);
+
+    // Copy input data to GPU
+    copy_data_to_gpu(hw, thandle, input_buf, input_size, input_buf_dev);
+
+    // Perform GPU transpose
+    assign_gpu<T>(thandle, output_buf_dev, output_dims, output_labels, T{1}, input_buf_dev,
+                  input_dims, input_labels, true);
+
+    // Clean up temporary input buffer
+    free_device_buffers(hw, input_buf_dev, input_size);
+
+    return gpu_trans;
+  }
+#endif
+
+  // CPU transpose
+  assign<T>(output_buf, output_dims, output_labels, T{1}, input_buf, input_dims, input_labels,
+            true);
+
+  return gpu_trans;
+}
+
 template<typename T, typename T1, typename T2, typename T3>
 void block_multiply(
 #if defined(USE_CUDA) || defined(USE_HIP) || defined(USE_DPCPP)

src/tamm/multop.hpp

@@ -490,6 +490,31 @@ class MultOp: public Op {
       std::cout << "\t Reduction A size = " << AR << std::endl;
       std::cout << "\t Reduction B size = " << BR << std::endl;
 
+      std::cout << "\t LHS_block sizes = ";
+      for(auto& d: lhs_dims) { std::cout << d << " "; }
+      std::cout << std::endl;
+      std::cout << "\t RHS1_block sizes = ";
+      for(auto& d: rhs1_dims) { std::cout << d << " "; }
+      std::cout << std::endl;
+      std::cout << "\t RHS2_block sizes = ";
+      for(auto& d: rhs2_dims) { std::cout << d << " "; }
+      std::cout << std::endl;
+      std::cout << "\t Transpose order LHS = C( ";
+      for(auto& d: lhs) { std::cout << d << " "; }
+      std::cout << ") <- C'( ";
+      for(auto& d: lhs_transpose_order) { std::cout << d << " "; }
+      std::cout << ")" << std::endl;
+      std::cout << "\t Transpose order RHS1 = A( ";
+      for(auto& d: rhs1) { std::cout << d << " "; }
+      std::cout << ") -> A'( ";
+      for(auto& d: rhs1_transpose_order) { std::cout << d << " "; }
+      std::cout << ")" << std::endl;
+      std::cout << "\t Transpose order RHS2 = B( ";
+      for(auto& d: rhs2) { std::cout << d << " "; }
+      std::cout << ") -> B'( ";
+      for(auto& d: rhs2_transpose_order) { std::cout << d << " "; }
+      std::cout << ")" << std::endl;
+
       task_id++;
     }
   }