IntenseWebs/openvino
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

MatMul spec update (#2765)

Browse Source 
Aligned specification with nGraph MatMul shape inference operation. Affects description of the behavior for 1D tensors.
This commit is contained in:
Katarzyna Mitrus 2020-11-06 16:41:36 +01:00 committed by GitHub
parent 0f00e7f703
commit 15d7919817
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 48 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
docs/ops/matrix/MatMul_1.md
View File

@ -12,21 +12,35 @@
Before matrix multiplication, there is an implicit shape alignment for input arguments. It consists of the following steps:
1. If rank of an input less than 2 it is unsqueezed to 2D tensor by adding axes with size 1 to the left of the shape. For example, if input has shape `[S]` it will be reshaped to `[1, S]`. It is applied for each input independently.
1. Applying transpositions specified by optional `transpose_a` and `transpose_b` attributes. Only the two right-most dimensions are transposed, other dimensions remain the same. Transpose attributes are ignored for 1D tensors.
2. Applied transpositions specified by optional `transpose_a` and `transpose_b` attributes.
2. One-dimensional tensors unsqueezing is applied for each input independently. The axes inserted in this step are not included in the output shape.
* If rank of the **first** input is equal to 1, it is always unsqueezed to 2D tensor **row vector** (regardless of `transpose_a`) by adding axes with size 1 at ROW_INDEX_DIM, to the **left** of the shape. For example `[S]` will be reshaped to `[1, S]`.
* If rank of the **second** input is equal to 1, it is always unsqueezed to 2D tensor **column vector** (regardless of `transpose_b`) by adding axes with size 1 at COL_INDEX_DIM, to the **right** of the shape. For example `[S]` will be reshaped to `[S, 1]`.
3. If ranks of input arguments are different after steps 1 and 2, each is unsqueezed from the left side of the shape by necessary number of axes to make both shapes of the same rank.
3. If ranks of input arguments are different after steps 1 and 2, the tensor with a smaller rank is unsqueezed from the left side of the shape by necessary number of axes to make both shapes of the same rank.
3. Usual rules of the broadcasting are applied for batch dimensions.
4. Usual rules of the broadcasting are applied for batch dimensions.
Two attributes, transpose_a and transpose_b specifies embedded transposition for two right-most dimension for the first and the second input tensors correspondingly. It implies swapping of ROW_INDEX_DIM and COL_INDEX_DIM in the corresponding input tensor. Batch dimensions are not affected by these attributes.
Temporary axes inserted in **step 2** are removed from the final output shape after multiplying.
After vector-matrix multiplication, the temporary axis inserted at ROW_INDEX_DIM is removed. After matrix-vector multiplication, the temporary axis inserted at COL_INDEX_DIM is removed.
Output shape of two 1D tensors multiplication `[S] x [S]` is squeezed to scalar.
Output shape inference logic examples (ND here means bigger than 1D):
* 1D x 1D: `[X] x [X] -> [1, X] x [X, 1] -> [1, 1] => []` (scalar)
* 1D x ND: `[X] x [B, ..., X, Y] -> [1, X] x [B, ..., X, Y] -> [B, ..., 1, Y] => [B, ..., Y]`
* ND x 1D: `[B, ..., X, Y] x [Y] -> [B, ..., X, Y] x [Y, 1] -> [B, ..., X, 1] => [B, ..., X]`
* ND x ND: `[B, ..., X, Y] x [B, ..., Y, Z] => [B, ..., X, Z]`
Two attributes, `transpose_a` and `transpose_b` specify embedded transposition for two right-most dimensions for the first and the second input tensors correspondingly. It implies swapping of ROW_INDEX_DIM and COL_INDEX_DIM in the corresponding input tensor. Batch dimensions and 1D tensors are not affected by these attributes.
**Attributes**
* *transpose_a*
* **Description**: transposes dimensions ROW_INDEX_DIM and COL_INDEX_DIM of the 1st input; 0 means no transpose, 1 means transpose
* **Description**: transposes dimensions ROW_INDEX_DIM and COL_INDEX_DIM of the 1st input; **False** means no transpose, **True** means transpose. It is ignored if first input is 1D tensor.
* **Range of values**: False or True
* **Type**: boolean
* **Default value**: False
@ -34,7 +48,7 @@ Two attributes, transpose_a and transpose_b specifies embedded transposition for
* *transpose_b*
* **Description**: transposes dimensions ROW_INDEX_DIM and COL_INDEX_DIM of the 2nd input; 0 means no transpose, 1 means transpose
* **Description**: transposes dimensions ROW_INDEX_DIM and COL_INDEX_DIM of the 2nd input; **False** means no transpose, **True** means transpose. It is ignored if second input is 1D tensor.
* **Range of values**: False or True
* **Type**: boolean
* **Default value**: False
@ -47,10 +61,14 @@ Two attributes, transpose_a and transpose_b specifies embedded transposition for
* **2**: Input batch of matrices B. Rank >= 1. Required.
**Outputs**
* **1**: Tensor with results of the multiplication.
**Example**
*Vector-matric multiplication*
*Vector-matrix multiplication*
```xml
<layer ... type="MatMul">
@ -65,7 +83,27 @@ Two attributes, transpose_a and transpose_b specifies embedded transposition for
</input>
<output>
<port id="2">
<dim>1</dim>
<dim>1000</dim>
</port>
</output>
</layer>
```
*Matrix-vector multiplication*
```xml
<layer ... type="MatMul">
<input>
<port id="0">
<dim>1000</dim>
<dim>1024</dim>
</port>
<port id="1">
<dim>1024</dim>
</port>
</input>
<output>
<port id="2">
<dim>1000</dim>
</port>
</output>
@ -95,14 +133,13 @@ Two attributes, transpose_a and transpose_b specifies embedded transposition for
</layer>
```
*Matrix-vector multiplication with embedded transposition of the second matrix*
*Vector-matrix multiplication with embedded transposition of the second matrix*
```xml
<layer ... type="MatMul">
<data transpose_b="true"/>
<input>
<port id="0">
<dim>1</dim>
<dim>1024</dim>
</port>
<port id="1">
@ -112,7 +149,6 @@ Two attributes, transpose_a and transpose_b specifies embedded transposition for
</input>
<output>
<port id="2">
<dim>1</dim>
<dim>1000</dim>
</port>
</output>