GatherND

GatherND - 29

Version

  • name: GatherND (GitHub)

  • domain: main

  • since_version: 29

  • function: False

  • support_level: SupportType.COMMON

  • shape inference: True

This version of the operator has been available since version 29.

Summary

Given data tensor of rank r >= 1, indices tensor of rank q >= 1, and batch_dims integer b, this operator gathers slices of data into an output tensor of rank q + r - indices_shape[-1] - 1 - b.

Let k = indices_shape[-1]. Each length-k tuple in indices selects an element or slice of data.

The leading b dimensions of data and indices are batch dimensions. Each tuple indexes the next k dimensions of data, starting at axis b (axes are zero-based).

The inputs must satisfy the following constraints:

  1. r >= 1 and q >= 1.

  2. The first b dimensions of the shape of indices tensor and data tensor must be equal.

  3. batch_dims must satisfy 0 <= b < min(q, r).

  4. indices_shape[-1] must be between 1 and r-b, inclusive.

  5. For each tuple component i, 0 <= i < indices_shape[-1], the index must satisfy -data_shape[b+i] <= indices[...,i] < data_shape[b+i]. It is an error if any of the index values are out of bounds.

The output shape is indices_shape[:-1] + data_shape[b+k:], where + denotes shape concatenation. For each coordinate tuple p in indices_shape[:-1], the selected value or slice is output[p] = data[p[:b] + tuple(indices[p])], using tuple concatenation for the data coordinate. Unspecified trailing data axes select the entire slice. When k = r-b, each selected value is a scalar. Negative indices count backwards from the end of the corresponding data dimension. Within the same batch, repeated index tuples select the same value or slice at multiple output positions.

Example 1

batch_dims = 0
data    = [[0,1],[2,3]]   # data_shape    = [2, 2]
indices = [[0,0],[1,1]]   # indices_shape = [2, 2]
output  = [0,3]           # output_shape  = [2]

Example 2

batch_dims = 0
data    = [[0,1],[2,3]]  # data_shape    = [2, 2]
indices = [[1],[0]]      # indices_shape = [2, 1]
output  = [[2,3],[0,1]]  # output_shape  = [2, 2]

Example 3

batch_dims = 0
data    = [[[0,1],[2,3]],[[4,5],[6,7]]] # data_shape    = [2, 2, 2]
indices = [[0,1],[1,0]]                 # indices_shape = [2, 2]
output  = [[2,3],[4,5]]                 # output_shape  = [2, 2]

Example 4

batch_dims = 0
data    = [[[0,1],[2,3]],[[4,5],[6,7]]] # data_shape    = [2, 2, 2]
indices = [[[0,1]],[[1,0]]]             # indices_shape = [2, 1, 2]
output  = [[[2,3]],[[4,5]]]             # output_shape  = [2, 1, 2]

Example 5

batch_dims = 1
data    = [[[0,1],[2,3]],[[4,5],[6,7]]] # data_shape    = [2, 2, 2]
indices = [[1],[0]]                     # indices_shape = [2, 1]
output  = [[2,3],[4,5]]                 # output_shape  = [2, 2]

Opset 29 adds support for int32 indices; int64 indices remain supported.

Attributes

  • batch_dims - INT (default is 0):

    The number of leading batch dimensions shared by data and indices. Index tuples address data axes starting at axis batch_dims.

Inputs

  • data (heterogeneous) - T:

    Tensor of rank r >= 1.

  • indices (heterogeneous) - Tind:

    Tensor of rank q >= 1. Each index must be in [-s, s-1], where s is the size of the corresponding data axis after the batch dimensions. An out-of-bounds index is an error.

Outputs

  • output (heterogeneous) - T:

    Tensor of rank q + r - indices_shape[-1] - 1 - batch_dims.

Type Constraints

  • T in ( tensor(bfloat16), tensor(bool), tensor(complex128), tensor(complex64), tensor(double), tensor(float), tensor(float16), tensor(int16), tensor(int32), tensor(int64), tensor(int8), tensor(string), tensor(uint16), tensor(uint32), tensor(uint64), tensor(uint8) ):

    Constrain input and output types to any tensor type.

  • Tind in ( tensor(int32), tensor(int64) ):

    Constrain indices to int32 or int64 tensors.

Examples

_selected_kv_int32_indices

import numpy as np
import onnx

node = onnx.helper.make_node(
    "GatherND", ["cache", "positions"], ["selected"], batch_dims=1
)
cache = np.arange(24, dtype=np.float32).reshape(2, 4, 3)
positions = np.array([[[[0], [2]]], [[[1], [-1]]]], dtype=np.int32)
selected = np.stack([cache[0, [[0, 2]]], cache[1, [[1, 3]]]])
expect(
    node,
    inputs=[cache, positions],
    outputs=[selected],
    name="test_gathernd_selected_kv_int32_indices",
)

_int32

import numpy as np
import onnx

node = onnx.helper.make_node(
    "GatherND",
    inputs=["data", "indices"],
    outputs=["output"],
)

data = np.array([[0, 1], [2, 3]], dtype=np.int32)
indices = np.array([[0, 0], [1, 1]], dtype=np.int64)
output = gather_nd_impl(data, indices, 0)
expected_output = np.array([0, 3], dtype=np.int32)
assert np.array_equal(output, expected_output)
expect(
    node,
    inputs=[data, indices],
    outputs=[output],
    name="test_gathernd_example_int32",
)

_float32

import numpy as np
import onnx

node = onnx.helper.make_node(
    "GatherND",
    inputs=["data", "indices"],
    outputs=["output"],
)

data = np.array([[[0, 1], [2, 3]], [[4, 5], [6, 7]]], dtype=np.float32)
indices = np.array([[[0, 1]], [[1, 0]]], dtype=np.int64)
output = gather_nd_impl(data, indices, 0)
expected_output = np.array([[[2, 3]], [[4, 5]]], dtype=np.float32)
assert np.array_equal(output, expected_output)
expect(
    node,
    inputs=[data, indices],
    outputs=[output],
    name="test_gathernd_example_float32",
)

_int32_batchdim_1

import numpy as np
import onnx

node = onnx.helper.make_node(
    "GatherND",
    inputs=["data", "indices"],
    outputs=["output"],
    batch_dims=1,
)

data = np.array([[[0, 1], [2, 3]], [[4, 5], [6, 7]]], dtype=np.int32)
indices = np.array([[1], [0]], dtype=np.int64)
output = gather_nd_impl(data, indices, 1)
expected_output = np.array([[2, 3], [4, 5]], dtype=np.int32)
assert np.array_equal(output, expected_output)
expect(
    node,
    inputs=[data, indices],
    outputs=[output],
    name="test_gathernd_example_int32_batch_dim1",
)

GatherND - 13

Version

  • name: GatherND (GitHub)

  • domain: main

  • since_version: 13

  • function: False

  • support_level: SupportType.COMMON

  • shape inference: True

This version of the operator has been available since version 13.

Summary

Given data tensor of rank r >= 1, indices tensor of rank q >= 1, and batch_dims integer b, this operator gathers slices of data into an output tensor of rank q + r - indices_shape[-1] - 1 - b.

Let k = indices_shape[-1]. Each length-k tuple in indices selects an element or slice of data.

The leading b dimensions of data and indices are batch dimensions. Each tuple indexes the next k dimensions of data, starting at axis b (axes are zero-based).

The inputs must satisfy the following constraints:

  1. r >= 1 and q >= 1.

  2. The first b dimensions of the shape of indices tensor and data tensor must be equal.

  3. batch_dims must satisfy 0 <= b < min(q, r).

  4. indices_shape[-1] must be between 1 and r-b, inclusive.

  5. For each tuple component i, 0 <= i < indices_shape[-1], the index must satisfy -data_shape[b+i] <= indices[...,i] < data_shape[b+i]. It is an error if any of the index values are out of bounds.

The output shape is indices_shape[:-1] + data_shape[b+k:], where + denotes shape concatenation. For each coordinate tuple p in indices_shape[:-1], the selected value or slice is output[p] = data[p[:b] + tuple(indices[p])], using tuple concatenation for the data coordinate. Unspecified trailing data axes select the entire slice. When k = r-b, each selected value is a scalar. Negative indices count backwards from the end of the corresponding data dimension. Within the same batch, repeated index tuples select the same value or slice at multiple output positions.

Example 1

batch_dims = 0
data    = [[0,1],[2,3]]   # data_shape    = [2, 2]
indices = [[0,0],[1,1]]   # indices_shape = [2, 2]
output  = [0,3]           # output_shape  = [2]

Example 2

batch_dims = 0
data    = [[0,1],[2,3]]  # data_shape    = [2, 2]
indices = [[1],[0]]      # indices_shape = [2, 1]
output  = [[2,3],[0,1]]  # output_shape  = [2, 2]

Example 3

batch_dims = 0
data    = [[[0,1],[2,3]],[[4,5],[6,7]]] # data_shape    = [2, 2, 2]
indices = [[0,1],[1,0]]                 # indices_shape = [2, 2]
output  = [[2,3],[4,5]]                 # output_shape  = [2, 2]

Example 4

batch_dims = 0
data    = [[[0,1],[2,3]],[[4,5],[6,7]]] # data_shape    = [2, 2, 2]
indices = [[[0,1]],[[1,0]]]             # indices_shape = [2, 1, 2]
output  = [[[2,3]],[[4,5]]]             # output_shape  = [2, 1, 2]

Example 5

batch_dims = 1
data    = [[[0,1],[2,3]],[[4,5],[6,7]]] # data_shape    = [2, 2, 2]
indices = [[1],[0]]                     # indices_shape = [2, 1]
output  = [[2,3],[4,5]]                 # output_shape  = [2, 2]

Attributes

  • batch_dims - INT (default is 0):

    The number of leading batch dimensions shared by data and indices. Index tuples address data axes starting at axis batch_dims.

Inputs

  • data (heterogeneous) - T:

    Tensor of rank r >= 1.

  • indices (heterogeneous) - tensor(int64):

    Tensor of rank q >= 1. Each index must be in [-s, s-1], where s is the size of the corresponding data axis after the batch dimensions. An out-of-bounds index is an error.

Outputs

  • output (heterogeneous) - T:

    Tensor of rank q + r - indices_shape[-1] - 1 - batch_dims.

Type Constraints

  • T in ( tensor(bfloat16), tensor(bool), tensor(complex128), tensor(complex64), tensor(double), tensor(float), tensor(float16), tensor(int16), tensor(int32), tensor(int64), tensor(int8), tensor(string), tensor(uint16), tensor(uint32), tensor(uint64), tensor(uint8) ):

    Constrain input and output types to any tensor type.

GatherND - 12

Version

  • name: GatherND (GitHub)

  • domain: main

  • since_version: 12

  • function: False

  • support_level: SupportType.COMMON

  • shape inference: True

This version of the operator has been available since version 12.

Summary

Given data tensor of rank r >= 1, indices tensor of rank q >= 1, and batch_dims integer b, this operator gathers slices of data into an output tensor of rank q + r - indices_shape[-1] - 1 - b.

indices is an q-dimensional integer tensor, best thought of as a (q-1)-dimensional tensor of index-tuples into data, where each element defines a slice of data

batch_dims (denoted as b) is an integer indicating the number of batch dimensions, i.e the leading b number of dimensions of data tensor and indices are representing the batches, and the gather starts from the b+1 dimension.

Some salient points about the inputs’ rank and shape:

  1. r >= 1 and q >= 1 are to be honored. There is no dependency condition to be met between ranks r and q

  2. The first b dimensions of the shape of indices tensor and data tensor must be equal.

  3. b < min(q, r) is to be honored.

  4. The indices_shape[-1] should have a value between 1 (inclusive) and rank r-b (inclusive)

  5. All values in indices are expected to be within bounds [-s, s-1] along axis of size s (i.e.) -data_shape[i] &lt;= indices[...,i] &lt;= data_shape[i] - 1. It is an error if any of the index values are out of bounds.

The output is computed as follows:

The output tensor is obtained by mapping each index-tuple in the indices tensor to the corresponding slice of the input data.

  1. If indices_shape[-1] &gt; r-b => error condition

  2. If indices_shape[-1] == r-b, since the rank of indices is q, indices can be thought of as N (q-b-1)-dimensional tensors containing 1-D tensors of dimension r-b, where N is an integer equals to the product of 1 and all the elements in the batch dimensions of the indices_shape. Let us think of each such r-b ranked tensor as indices_slice. Each scalar value corresponding to data[0:b-1,indices_slice] is filled into the corresponding location of the (q-b-1)-dimensional tensor to form the output tensor (Example 1 below)

  3. If indices_shape[-1] &lt; r-b, since the rank of indices is q, indices can be thought of as N (q-b-1)-dimensional tensor containing 1-D tensors of dimension &lt; r-b. Let us think of each such tensors as indices_slice. Each tensor slice corresponding to data[0:b-1, indices_slice , :] is filled into the corresponding location of the (q-b-1)-dimensional tensor to form the output tensor (Examples 2, 3, 4 and 5 below)

This operator is the inverse of ScatterND.

Example 1

batch_dims = 0

data = [[0,1],[2,3]] # data_shape = [2, 2]

indices = [[0,0],[1,1]] # indices_shape = [2, 2]

output = [0,3] # output_shape = [2]

Example 2

batch_dims = 0

data = [[0,1],[2,3]] # data_shape = [2, 2]

indices = [[1],[0]] # indices_shape = [2, 1]

output = [[2,3],[0,1]] # output_shape = [2, 2]

Example 3

batch_dims = 0

data = [[[0,1],[2,3]],[[4,5],[6,7]]] # data_shape = [2, 2, 2]

indices = [[0,1],[1,0]] # indices_shape = [2, 2]

output = [[2,3],[4,5]] # output_shape = [2, 2]

Example 4

batch_dims = 0

data = [[[0,1],[2,3]],[[4,5],[6,7]]] # data_shape = [2, 2, 2]

indices = [[[0,1]],[[1,0]]] # indices_shape = [2, 1, 2]

output = [[[2,3]],[[4,5]]] # output_shape = [2, 1, 2]

Example 5

batch_dims = 1

data = [[[0,1],[2,3]],[[4,5],[6,7]]] # data_shape = [2, 2, 2]

indices = [[1],[0]] # indices_shape = [2, 1]

output = [[2,3],[4,5]] # output_shape = [2, 2]

Attributes

  • batch_dims - INT (default is 0):

    The number of batch dimensions. The gather of indexing starts from dimension of data[batch_dims:]

Inputs

  • data (heterogeneous) - T:

    Tensor of rank r >= 1.

  • indices (heterogeneous) - tensor(int64):

    Tensor of rank q >= 1. All index values are expected to be within bounds [-s, s-1] along axis of size s. It is an error if any of the index values are out of bounds.

Outputs

  • output (heterogeneous) - T:

    Tensor of rank q + r - indices_shape[-1] - 1.

Type Constraints

  • T in ( tensor(bool), tensor(complex128), tensor(complex64), tensor(double), tensor(float), tensor(float16), tensor(int16), tensor(int32), tensor(int64), tensor(int8), tensor(string), tensor(uint16), tensor(uint32), tensor(uint64), tensor(uint8) ):

    Constrain input and output types to any tensor type.

GatherND - 11

Version

  • name: GatherND (GitHub)

  • domain: main

  • since_version: 11

  • function: False

  • support_level: SupportType.COMMON

  • shape inference: True

This version of the operator has been available since version 11.

Summary

Given data tensor of rank r >= 1, and indices tensor of rank q >= 1, this operator gathers slices of data into an output tensor of rank q + r - indices_shape[-1] - 1.

indices is an q-dimensional integer tensor, best thought of as a (q-1)-dimensional tensor of index-tuples into data, where each element defines a slice of data

Some salient points about the inputs’ rank and shape:

  1. r >= 1 and q >= 1 are to be honored. There is no dependency condition to be met between ranks r and q

  2. The indices_shape[-1] should have a value between 1 (inclusive) and rank r (inclusive)

  3. All values in indices are expected to be within bounds [-s, s-1] along axis of size s (i.e.) -data_shape[i] &lt;= indices[...,i] &lt;= data_shape[i] - 1. It is an error if any of the index values are out of bounds.

The output is computed as follows:

The output tensor is obtained by mapping each index-tuple in the indices tensor to the corresponding slice of the input data.

  1. If indices_shape[-1] &gt; r => error condition

  2. If indices_shape[-1] == r, since the rank of indices is q, indices can be thought of as a (q-1)-dimensional tensor containing 1-D tensors of dimension r. Let us think of each such r ranked tensor as indices_slice. Each scalar value corresponding to data[indices_slice] is filled into the corresponding location of the (q-1)-dimensional tensor to form the output tensor (Example 1 below)

  3. If indices_shape[-1] &lt; r, since the rank of indices is q, indices can be thought of as a (q-1)-dimensional tensor containing 1-D tensors of dimension &lt; r. Let us think of each such tensors as indices_slice. Each tensor slice corresponding to data[indices_slice , :] is filled into the corresponding location of the (q-1)-dimensional tensor to form the output tensor (Examples 2, 3, and 4 below)

This operator is the inverse of ScatterND.

Example 1

data = [[0,1],[2,3]] # data_shape = [2, 2]

indices = [[0,0],[1,1]] # indices_shape = [2, 2]

output = [0,3] # output_shape = [2]

Example 2

data = [[0,1],[2,3]] # data_shape = [2, 2]

indices = [[1],[0]] # indices_shape = [2, 1]

output = [[2,3],[0,1]] # output_shape = [2, 2]

Example 3

data = [[[0,1],[2,3]],[[4,5],[6,7]]] # data_shape = [2, 2, 2]

indices = [[0,1],[1,0]] # indices_shape = [2, 2]

output = [[2,3],[4,5]] # output_shape = [2, 2]

Example 4

data = [[[0,1],[2,3]],[[4,5],[6,7]]] # data_shape = [2, 2, 2]

indices = [[[0,1]],[[1,0]]] # indices_shape = [2, 1, 2]

output = [[[2,3]],[[4,5]]] # output_shape = [2, 1, 2]

Inputs

  • data (heterogeneous) - T:

    Tensor of rank r >= 1.

  • indices (heterogeneous) - tensor(int64):

    Tensor of rank q >= 1. All index values are expected to be within bounds [-s, s-1] along axis of size s. It is an error if any of the index values are out of bounds.

Outputs

  • output (heterogeneous) - T:

    Tensor of rank q + r - indices_shape[-1] - 1.

Type Constraints

  • T in ( tensor(bool), tensor(complex128), tensor(complex64), tensor(double), tensor(float), tensor(float16), tensor(int16), tensor(int32), tensor(int64), tensor(int8), tensor(string), tensor(uint16), tensor(uint32), tensor(uint64), tensor(uint8) ):

    Constrain input and output types to any tensor type.