From: Andrey Miroshnikov <andrey@technepisteme.xyz>
Date: Tue, 17 Oct 2023 08:59:28 +0000 (+0000)
Subject: Adding initial notes for matrix remap example
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=afdc384bb78d1ae7938eb0d5f15ba785863d4043;p=libreriscv.git

Adding initial notes for matrix remap example
---

diff --git a/openpower/sv/cookbook/remap_matrix.mdwn b/openpower/sv/cookbook/remap_matrix.mdwn
new file mode 100644
index 000000000..6542e8491
--- /dev/null
+++ b/openpower/sv/cookbook/remap_matrix.mdwn
@@ -0,0 +1,79 @@
+# SVP64/Vector+1 REMAP Worked Example: Matrix Multiply
+
+TODO: Include screenshots
+
+One of the most powerful and versatile modes of the REMAP engine (a part of
+the SVP64/Vector+1 feature set) is the ability to perform matrix
+multiplication with all elements within a scalar register file.
+
+This is done by converting the index used to iterate over the operand and
+result matrices to the actual index inside the scalar register file.
+
+## Worked example - manual (conventional method)
+
+The matrix multiply looks like this:
+
+    mat_X * mat_Y = mat_Z
+
+When multiplying non-square matrices (rows != columns), to determine the
+dimension of the result when matrix X has `a` rows and `b` columns and matrix
+Y has `b` rows and `c` columns:
+
+    X_axb * Y_bxc = Z_axc
+
+The result matrix will have number of rows of the first matrix, and number of
+columns of the second matrix.
+
+
+For this example, the following values will be used for the operand matrices X
+and Y, result Z shown for completeness.
+
+    X =| 1 2 3 |  Y =  |  6  7 |  Z = |  52  58 |
+       | 3 4 5 |       |  8  9 |      | 100 112 |
+                       | 10 11 |
+
+Matrix X has 2 rows, 3 columns (2x3), and matrix Y has 3 rows, 2 columns.
+
+To determine the final dimensions of the resultant matrix Z, take the number of rows from matrix X (2) and number of columns from matrix Y (2).
+
+For the algorithm, assign indeces to matrices as follows:
+
+    Index | 0 1 2 3 4 5 |
+    Mat X | 1 2 3 3 4 5 |
+
+    Index | 0 1 2 3  4  5 |
+    Mat Y | 6 7 8 9 10 11 |
+
+    Index |  0  1   2   3 |
+    Mat Z | 52 58 100 112 |
+
+The method usually taught in linear algebra course to students is the following:
+
+1. Start with the first row of the first matrix, and first column of the second matrix.
+2. Multiply each element in the row by each element in the column, and sum the result.
+3. Store result in the first row, first column entry.
+
+Equation: (TODO)
+
+    A(i, j) * B(j, k) = C(i, k)
+
+Calculations:
+
+    | 1 2 3 |   |  6  7 | = | (1*6 + 2*8 + 3*10) (1*7 + 2*9 3*11) |
+    | 3 4 5 | * |  8  9 |   | (3*6 + 4*8 + 5*10) (3*7 + 4*9 5*11) |
+                | 10 11 |
+                
+    | 1 2 3 |   |  6  7 | = | ( 6 + 16 + 30) ( 7 + 18 + 33) |
+    | 3 4 5 | * |  8  9 |   | (18 + 32 + 50) (21 + 36 + 55) |
+                | 10 11 |
+                
+    | 1 2 3 |   |  6  7 | = |  52  58 |
+    | 3 4 5 | * |  8  9 |   | 100 112 |
+                | 10 11 |
+
+## Appendix
+
+### Links
+
+- [Online matrix calculator](https://matrix.reshish.com/multCalculation.php)
+- [LibreSOC matrix multiply REMAP]()