diff --git a/docs/doxygen/ie_docs.xml b/docs/doxygen/ie_docs.xml index cfa01b3258e..b159fdbb459 100644 --- a/docs/doxygen/ie_docs.xml +++ b/docs/doxygen/ie_docs.xml @@ -153,6 +153,7 @@ + diff --git a/docs/ops/movement/GatherND_5.md b/docs/ops/movement/GatherND_5.md new file mode 100644 index 00000000000..cfb156c7f15 --- /dev/null +++ b/docs/ops/movement/GatherND_5.md @@ -0,0 +1,179 @@ +## GatherND {#openvino_docs_ops_movement_GatherND_5} + +**Versioned name**: *GatherND-5* + +**Category**: Data movement operations + +**Short description**: *GatherND* gathers slices from input tensor into a tensor of a shape specified by indices. + +**Detailed description**: *GatherND* gathers slices from `data` by `indices` and forms a tensor of a 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 +insert it into the output at position `i_0, ..., i_{K-2}` as 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, i.e. `indices.shape[-1] <= data.rank`. +The shape of the output can be computed as `indices.shape[:-1] + data.shape[indices.shape[-1]:]`. + +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]]] +``` + +**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. +In case 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):]`. + * **Range of values**: integer number and belongs to `[0; min(data.rank, indices.rank))` + * **Type**: int + * **Default value**: 0 + * **Required**: *no* + +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 example 6 shows 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 = (6, 1) +``` + +**Inputs**: + +* **1**: `data` tensor of type *T*. This is a tensor of a rank not less than 1. Required. + +* **2**: `indices` tensor of type *T_IND*. This is a tensor of a rank not less than 1. +It requires that all indices from this tensor will be in a range `[0, s-1]` where `s` is 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** + +```xml + + + + + 1000 + 256 + 10 + 15 + + + 25 + 125 + 3 + + + + + 25 + 125 + 15 + + + +``` + +```xml + + + + + 30 + 2 + 100 + 35 + + + 30 + 2 + 3 + 1 + + + + + 60 + 3 + 35 + + + +``` diff --git a/docs/ops/opset5.md b/docs/ops/opset5.md index c2083aa39d0..4ddb3eb6549 100644 --- a/docs/ops/opset5.md +++ b/docs/ops/opset5.md @@ -54,6 +54,7 @@ declared in `namespace opset5`. * [Floor](arithmetic/Floor_1.md) * [FloorMod](arithmetic/FloorMod_1.md) * [Gather](movement/Gather_1.md) +* [GatherND_5](movement/GatherND_5.md) * [GatherTree](movement/GatherTree_1.md) * [Gelu](activation/GELU_2.md) * [Greater](comparison/Greater_1.md)