doc: project report iteration

Co-authored-by: Vincent Gerlach <[email protected]>

Author: Integer-Ctrl

README.md

@@ -16,10 +16,10 @@ This repository includes:
 
 The weekly tasks from the lab can be found here: [scalable-analyses](https://github.com/scalable-analyses/pbtc/tree/main/lab)
 
-## Technical Documentation
+## CMake Library
 
-A detailed technical documentation of our implementation including the design decisions and solutions to the lab tasks, and explanations of the source code is available on our [project website](https://integer-ctrl.github.io/machine-learning-compilers/).
+To make the compiler easy to integrate into other projects, we structured it as a CMake library. This allows users to include and build upon our functionality directly in their own CMake-based projects. More details about the library and how to use it can be found in the [user-guide](https://github.com/Integer-Ctrl/machine-learning-compilers/blob/main/cmake-library/README.md).
 
-## CMake Library
+## Technical Documentation
 
-To make the compiler easy to integrate into other projects, we structured it as a CMake library. This allows users to include and build upon our functionality directly in their own CMake-based projects. More details about the library and how to use it can be found in the [user-guide.md](https://github.com/Integer-Ctrl/machine-learning-compilers/cmake-library/user-guide.md).
+A detailed technical documentation of our implementation including the design decisions and solutions to the lab tasks, and explanations of the source code is available on our [project website](https://integer-ctrl.github.io/machine-learning-compilers/).

cmake-library/user-guide.md cmake-library/README.mdcmake-library/user-guide.md renamed to cmake-library/README.md

@@ -154,7 +154,7 @@ mlc::Error error = mlc::contraction(in0, in1, out, "[0,1,2],[3,4,1]->[0,3,4,2]")
 
 In the example above, the contraction operation takes two input tensors `in0` and `in1`, and produces an output tensor `out`. The expression `"[0,1,2],[3,4,1]->[0,3,4,2]"` defines that the dimensions with IDs `0`, `2`, `3`and `4` are retained in the output tensor, while the dimensions with IDs `1` is contracted. The output tensor will have the dimensions `[5, 5, 2, 3]`.
 
-To further advance the contraction operation, a first touch primitive and a last touch primitive can be specified. The first touch primitive is applied to the output tensor before the contraction operation, while the last touch primitive is applied to the output tensor after the contraction operation. The supported primitives are `mlc::UnaryType::None`, `mlc::UnaryType::Zero`, `mlc::UnaryType::Identity` and `mlc::UnaryType::ReLu`.
+To further advance the contraction operation, a first touch primitive and a last touch primitive can be specified. The first touch primitive is applied to the output tensor before the contraction operation, while the last touch primitive is applied to the output tensor after the contraction operation. The supported primitives are `mlc::UnaryType::None`, `mlc::UnaryType::Zero`, `mlc::UnaryType::Identity` and `mlc::UnaryType::ReLU`.
 
 ```cpp
 #include <MachineLearningCompiler/Tensor.h>

docs_sphinx/Doxyfile.in

@@ -864,7 +864,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = "../src/" "../includes/"
+INPUT                  = "../src/" "../include/"
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

docs_sphinx/chapters/report_individual.rst

@@ -9,10 +9,10 @@ Backend
 -------
 
 User Interface
-""""""""""""""
+^^^^^^^^^^^^^^
 
 1. setup
-^^^^^^^^
+""""""""
 
 **Task**: Begin implementing the ``setup`` function of the class ``einsum::backend::TensorOperation`` for binary tensor contractions.
 Parse the configuration parameters passed to the function and generate the corresponding (BR)GEMM kernel at runtime.
@@ -246,10 +246,10 @@ primitives in combination with a naive version. The tests are located in the fol
     TEST_CASE("Test tensor operation with outer loop with first touch: unary (zero, relu, copy) & main kernel: brgemm & last touch: unary (zero, relu, copy)", "[tensor_operation][unary][brgemm][correctness]")
 
 Performance Benchmarking
-------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 1. Performance
-^^^^^^^^^^^^^^
+""""""""""""""
 
 **Task**: Benchmark the performance of your implementation for the above examples. Report the measured performance in GFLOPS.
 
@@ -292,7 +292,7 @@ Tensor contraction using the Zero, BRGEMM and ReLU primitives:
     BM_tensor_Zero+BRGEMM+RELU/size_a:262144/size_b:262144/size_c:1048576/config:2/min_warmup_time:0.300_cv           0.32 %          0.32 %            10      0.32%
 
 2. Own Setups
-^^^^^^^^^^^^^
+"""""""""""""
 
 **Task**: Design your own setups. Which setups achieve a high performance and which setups are slow?
 
@@ -354,14 +354,14 @@ Tensor contraction using the Zero, BRGEMM and ReLU primitives:
 
 
 Shared Memory Parallelization
------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In the shared memory domain, loops can be parallelized at any point within the nested loop structure. However, to simplify the
 implementation, we only parallelize the outermost loops. In other words, we do not parallelize loops that are nested inside
 sequential loops.
 
 1. execute_iter_parallel
-^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""""
 
 **Task**: Implement the function ``execute_iter_parallel``, which parallelizes a binary tensor contraction in the shared memory domain.
 
@@ -727,9 +727,9 @@ And validated with some additional tests: File: ``TensorOperation.test.cpp``.
 .. code-block:: cpp
 
     bool mini_jit::TensorOperation::isValidPrimStrides(const std::span<const TensorConfig::dim_t> &dim,
-                                                    const std::span<const TensorConfig::exec_t> &exec,
-                                                    const std::span<const int64_t> &strides_in0, const std::span<const int64_t> &strides_out,
-                                                    const TensorConfig::prim_t main_prim)
+                                                       const std::span<const TensorConfig::exec_t> &exec,
+                                                       const std::span<const int64_t> &strides_in0, const std::span<const int64_t> &strides_out,
+                                                       const TensorConfig::prim_t main_prim)
     {
     // ...
 

docs_sphinx/chapters/tensor_operations.rst

@@ -72,6 +72,8 @@
     "source_branch": "main",
     "source_directory": "docs_sphinx/",
 }
+html_title = "Machine Learning Compilers"
+language = "en"
 
 # html_theme = 'sphinx_rtd_theme'
 # html_theme_options = {

docs_sphinx/conf.py

@@ -7,15 +7,15 @@ Machine Learning Compilers
 ==========================
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 1
    :caption: GETTING STARTED
    :glob:
 
    getting_started/building_project.rst
    getting_started/building_docs.rst
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 2
    :caption: CHAPTERS
    :glob:
 
@@ -29,7 +29,7 @@ Machine Learning Compilers
    chapters/report_individual.rst
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 2
    :caption: API
    :glob:
 

docs_sphinx/index.rst

@@ -42,7 +42,7 @@ mlc::Error mlc::EinsumOperation::execute(const std::vector<std::reference_wrappe
     return error;
   }
 
-  Error checkError = hasSameDimensions<std::reference_wrapper<const Tensor>>(inputs);
+  Error checkError = hasSameDimensions<std::reference_wrapper<const Tensor>>(inputs, output);
   if (checkError.type != ErrorType::None)
   {
     return checkError;
@@ -58,7 +58,7 @@ mlc::Error mlc::EinsumOperation::execute(const std::vector<const Tensor *> &inpu
     return error;
   }
 
-  Error checkError = hasSameDimensions<const Tensor *>(inputs);
+  Error checkError = hasSameDimensions<const Tensor *>(inputs, output);
   if (checkError.type != ErrorType::None)
   {
     return checkError;

src/interface/Einsum.cpp

@@ -92,10 +92,26 @@ namespace mlc
     return {mlc::ErrorType::None, "Success"};
   }
 
-  template <typename T> inline Error EinsumOperation::hasSameDimensions(const std::vector<T> &inputs)
+  template <typename T> inline Error EinsumOperation::hasSameDimensions(const std::vector<T> &inputs, const Tensor &output)
   {
-    std::vector<mini_jit::EinsumTree::EinsumNode *> nodesToProcess = {einsumTree.get_root()};
     auto &sortedDimSizes = einsumTree.get_sorted_dim_sizes();
+    const mini_jit::EinsumTree::EinsumNode *root = einsumTree.getRoot();
+
+    if (output->dim_sizes.size() != root->output_dim_ids.size())
+    {
+      return {ErrorType::ExecuteWrongDimension, "The count of dimensions do not match in the output tensor."};
+    }
+
+    for (size_t i = 0; i < root->output_dim_ids.size(); i++)
+    {
+      if (output->dim_sizes[i] != static_cast<uint64_t>(sortedDimSizes[root->output_dim_ids[i]]))
+      {
+        return {ErrorType::ExecuteWrongDimension,
+                "The output tensor dimension has a different size than the size than the tensor it was setup up with."};
+      }
+    }
+
+    std::vector<mini_jit::EinsumTree::EinsumNode *> nodesToProcess = {einsumTree.get_root()};
     uint32_t processedInputs = 0;
     while (nodesToProcess.size() > 0)
     {
@@ -113,7 +129,7 @@ namespace mlc
 
         if (tensor->dim_sizes.size() != node->output_dim_ids.size())
         {
-          return {ErrorType::ExecuteWrongDimension, "The count of dimensions do not match."};
+          return {ErrorType::ExecuteWrongDimension, "The count of dimensions do not match in an input tensor."};
         }
 
         for (size_t i = 0; i < node->output_dim_ids.size(); i++)