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

GatherND_8 specification (#7739)

Browse Source 
* Add specifiation for GatherND_8 operation

* Update formula

* Add links to op spec

* Fix existed and add new example

* Correct output shape formula

* Add restriction for batch_dims values

* Add reference for gatherND-8 operation

* Update batch_dims=3 example

* Fix output shape in example

* fix lines length

* Fix typo

* Fix wrong shape

* Update note about calculation of out shape

* Apply suggestions from code review

Co-authored-by: Tatiana Savina <tatiana.savina@intel.com>

Co-authored-by: Tatiana Savina <tatiana.savina@intel.com>
This commit is contained in:
Anton Chetverikov 2021-10-21 14:52:09 +03:00 committed by GitHub
parent 0f282b687f
commit c9dc922f3c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 245 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/doxygen/ie_docs.xml
View File

@ -167,6 +167,7 @@ limitations under the License.
<tab type="user" title="Gather-8" url="@ref openvino_docs_ops_movement_Gather_8"/>
<tab type="user" title="GatherElements-6" url="@ref openvino_docs_ops_movement_GatherElements_6"/>
<tab type="user" title="GatherND-5" url="@ref openvino_docs_ops_movement_GatherND_5"/>
<tab type="user" title="GatherND-8" url="@ref openvino_docs_ops_movement_GatherND_8"/>
<tab type="user" title="Gelu-2" url="@ref openvino_docs_ops_activation_GELU_2"/>
<tab type="user" title="Gelu-7" url="@ref openvino_docs_ops_activation_GELU_7"/>
<tab type="user" title="GreaterEqual-1" url="@ref openvino_docs_ops_comparison_GreaterEqual_1"/>

12
docs/ops/movement/GatherND_5.md
View File

@ -52,11 +52,15 @@ output = [[[3, 4]],
* *batch_dims*
* **Description**: *batch_dims* (denoted as `b`) is a leading number of dimensions of `data` tensor and `indices` representing the batches,
and *GatherND* starts to gather from the `b+1` dimension.
It requires the first `b` dimensions in `data` and `indices` tensors to be equal.
In case non default value for *batch_dims* the output shape is calculated as
* **Description**: *batch_dims* (denoted as `b`) is a leading number of dimensions of `data` tensor
and `indices` representing the batches, and *GatherND* starts to gather from the `b+1` dimension.
It requires the first `b` dimensions in `data` and `indices` tensors to be equal.
In case of non-default value for *batch_dims*, the output shape is calculated as
`(multiplication of indices.shape[:b]) + indices.shape[b:-1] + data.shape[(indices.shape[-1] + b):]`.
**NOTE:** The calculation of output shape is incorrect for non-default *batch_dims* value greater than one.
For correct calculations use [GatherND_8](GatherND_8.md) operation**
* **Range of values**: integer number and belongs to `[0; min(data.rank, indices.rank))`
* **Type**: int
* **Default value**: 0

235
docs/ops/movement/GatherND_8.md Normal file
View File

@ -0,0 +1,235 @@
## GatherND <a name="GatherND"></a> {#openvino_docs_ops_movement_GatherND_8}
**Versioned name**: *GatherND-8*
**Category**: *Data movement*
**Short description**: *GatherND* gathers slices from input tensor into a tensor of the shape specified by indices.
**Detailed description**: *GatherND* gathers slices from `data` by `indices` and forms a tensor of the shape specified by `indices`.
`indices` is `K`-dimensional integer tensor or `K-1`-dimensional tensor of tuples with indices by which the operation
gathers elements or slices from `data` tensor. A position `i_0, ..., i_{K-2}` in the `indices` tensor corresponds to
a tuple with indices `indices[i_0, ..., i_{K-2}]` of a length equal to `indices.shape[-1]`. By this tuple with indices
the operation gathers a slice or an element from `data` tensor and inserts it into the output at the position
`i_0, ..., i_{K-2}` as described in the following formula:
`output[i_0, ..., i_{K-2},:,...,:] = data[indices[i_0, ..., i_{K-2}],:,...,:]`
The last dimension of `indices` tensor must be not greater than a rank of `data` tensor, meaning
`indices.shape[-1] <= data.rank`.
The shape of the output is calculated as `indices.shape[:batch_dims] + indices.shape[batch_dims:-1]`
if `indices.shape[-1] == data.rank - batch_dims` else
`indices.shape[:batch_dims] + list(indices.shape)[batch_dims:-1] + list(data.shape)[batch_dims + indices.shape[-1]:]`.
**Attributes**:
* *batch_dims*
* **Description**: *batch_dims* (denoted as `b`) is a leading number of dimensions of `data` tensor and `indices`
representing the batches, and *GatherND* starts to gather from the `b+1` dimension. It requires the first `b`
dimensions in `data` and `indices` tensors to be equal.
* **Range of values**: integer number that belongs to `[0; min(data.rank, indices.rank))`
* **Type**: int
* **Default value**: 0
* **Required**: *no*
**Inputs**:
* **1**: `data` tensor of type *T*. A tensor of a rank not less than 1. **Required.**
* **2**: `indices` tensor of type *T_IND*. A tensor of a rank not less than 1.
It requires all indices from this tensor to be in the range `[0, s-1]` where `s` is the corresponding dimension to
which this index is applied.
**Required.**
**Outputs**:
* **1**: Tensor with gathered values of type *T*.
**Types**
* *T*: any supported type.
* *T_IND*: any supported integer types.
**Examples**
Example 1 shows how *GatherND* operates with elements from `data` tensor:
```
indices = [[0, 0],
[1, 0]]
data = [[1, 2],
[3, 4]]
output = [1, 3]
```
Example 2 shows how *GatherND* operates with slices from `data` tensor:
```
indices = [[1], [0]]
data = [[1, 2],
[3, 4]]
output = [[3, 4],
[1, 2]]
```
Example 3 shows how *GatherND* operates when `indices` tensor has leading dimensions:
```
indices = [[[1]], [[0]]]
data = [[1, 2],
[3, 4]]
output = [[[3, 4]],
[[1, 2]]]
```
Example 4 shows how *GatherND* operates gathering elements for non-default *batch_dims* value:
```
batch_dims = 1
indices = [[1], <--- this is applied to the first batch
[0]] <--- this is applied to the second batch, shape = (2, 1)
data = [[1, 2], <--- the first batch
[3, 4]] <--- the second batch, shape = (2, 2)
output = [2, 3], shape = (2)
```
Example 5 shows how *GatherND* operates gathering slices for non-default *batch_dims* value:
```
batch_dims = 1
indices = [[1], <--- this is applied to the first batch
[0]] <--- this is applied to the second batch, shape = (2, 1)
data = [[[1, 2, 3, 4], [ 5, 6, 7, 8], [ 9, 10, 11, 12]] <--- the first batch
[[13, 14, 15, 16], [17, 18, 19, 20], [21, 22, 23, 24]]] <--- the second batch, shape = (2, 3, 4)
output = [[ 5, 6, 7, 8], [13, 14, 15, 16]], shape = (2, 4)
```
More complex examples 6 and 7 show how *GatherND* operates gathering slices with leading dimensions for non-default
*batch_dims* value:
```
batch_dims = 2
indices = [[[[1]], <--- this is applied to the first batch
[[0]],
[[2]]],
[[[0]],
[[2]],
[[2]]] <--- this is applied to the sixth batch
], shape = (2, 3, 1, 1)
data = [[[ 1, 2, 3, 4], <--- this is the first batch
[ 5, 6, 7, 8],
[ 9, 10, 11, 12]]
[[13, 14, 15, 16],
[17, 18, 19, 20],
[21, 22, 23, 24]] <--- this is the sixth batch
] <--- the second batch, shape = (2, 3, 4)
output = [[[ 2], [ 5], [11]], [[13], [19], [23]]], shape = (2, 3, 1)
```
```
batch_dims = 3
indices = [[[[1],
[0]],
[[3],
[2]]]
], shape = (1, 2, 2, 1)
data = [[[[ 1 2 3 4],
[ 5 6 7 8]],
[[ 9 10 11 12],
[13 14 15 16]]]
], shape = (1, 2, 2, 4)
output = [[[ 2 5],
[12 15]]
], shape = (1, 2, 2)
```
```xml
<layer id="1" type="GatherND">
<data batch_dims="0" />
<input>
<port id="0">
<dim>1000</dim>
<dim>256</dim>
<dim>10</dim>
<dim>15</dim>
</port>
<port id="1">
<dim>25</dim>
<dim>125</dim>
<dim>3</dim>
</port>
</input>
<output>
<port id="3">
<dim>25</dim>
<dim>125</dim>
<dim>15</dim>
</port>
</output>
</layer>
```
```xml
<layer id="1" type="GatherND">
<data batch_dims="2" />
<input>
<port id="0">
<dim>30</dim>
<dim>2</dim>
<dim>100</dim>
<dim>35</dim>
</port>
<port id="1">
<dim>30</dim>
<dim>2</dim>
<dim>3</dim>
<dim>1</dim>
</port>
</input>
<output>
<port id="3">
<dim>60</dim>
<dim>3</dim>
<dim>35</dim>
</port>
</output>
</layer>
```
```xml
<layer id="1" type="GatherND">
<data batch_dims="3" />
<input>
<port id="0">
<dim>1</dim>
<dim>64</dim>
<dim>64</dim>
<dim>320</dim>
</port>
<port id="1">
<dim>1</dim>
<dim>64</dim>
<dim>64</dim>
<dim>1</dim>
<dim>1</dim>
</port>
</input>
<output>
<port id="3">
<dim>1</dim>
<dim>64</dim>
<dim>64</dim>
<dim>1</dim>
</port>
</output>
</layer>
```

2
docs/ops/opset8.md
View File

@ -65,7 +65,7 @@ declared in `namespace opset8`.
* [FloorMod](arithmetic/FloorMod_1.md)
* [Gather](movement/Gather_8.md)
* [GatherElements](movement/GatherElements_6.md)
* [GatherND_5](movement/GatherND_5.md)
* [GatherND_8](movement/GatherND_8.md)
* [GatherTree](movement/GatherTree_1.md)
* [Gelu](activation/GELU_7.md)
* [Greater](comparison/Greater_1.md)