GatherElements

• Domain: ai.onnx

• Since version: 13

GatherElements takes two inputs data and indices of the same rank r >= 1 and an optional attribute axis that identifies an axis of data (by default, the outer-most axis, that is axis 0). It is an indexing operation that produces its output by indexing into the input data tensor at index positions determined by elements of the indices tensor. Its output shape is the same as the shape of indices and consists of one value (gathered from the data) for each element in indices.

For instance, in the 3-D case (r = 3), the output produced is determined by the following equations:

out[i][j][k] = input[index[i][j][k]][j][k] if axis = 0,
out[i][j][k] = input[i][index[i][j][k]][k] if axis = 1,
out[i][j][k] = input[i][j][index[i][j][k]] if axis = 2,

This operator is also the inverse of ScatterElements. It is similar to Torch’s gather operation.

Example 1:

data = [
    [1, 2],
    [3, 4],
]
indices = [
    [0, 0],
    [1, 0],
]
axis = 1
output = [
    [1, 1],
    [4, 3],
]

Example 2:

data = [
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9],
]
indices = [
    [1, 2, 0],
    [2, 0, 0],
]
axis = 0
output = [
    [4, 8, 3],
    [7, 2, 3],
]

Inputs

• data (T): Tensor of rank r >= 1.

• indices (Tind): Tensor of int32/int64 indices, with the same rank r as the input. 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 (T): Tensor of the same shape as indices.

Attributes

• axis (int): Which axis to gather on. Negative value means counting dimensions from the back. Accepted range is [-r, r-1] where r = rank(data).

Type Constraints

• T: Constrain input and output types to any tensor type. Allowed types: 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).

• Tind: Constrain indices to integer types Allowed types: tensor(int32), tensor(int64).

Examples

test_cc_gather_elements_0

Node:
  GatherElements(data, indices) -> (output)
  Attributes:
    axis = 1

Inputs:
  data: shape=(2, 2), dtype=float32
    [[1., 2.],
     [3., 4.]]
  indices: shape=(2, 2), dtype=int64
    [[0, 0],
     [1, 0]]

Outputs:
  output: shape=(2, 2), dtype=float32
    [[1., 1.],
     [4., 3.]]

test_cc_gather_elements_1

Node:
  GatherElements(data, indices) -> (output)
  Attributes:
    axis = 0

Inputs:
  data: shape=(3, 3), dtype=float32
    [[1., 2., 3.],
     [4., 5., 6.],
     [7., 8., 9.]]
  indices: shape=(2, 3), dtype=int64
    [[1, 2, 0],
     [2, 0, 0]]

Outputs:
  output: shape=(2, 3), dtype=float32
    [[4., 8., 3.],
     [7., 2., 3.]]

test_cc_gather_elements_negative_indices

Node:
  GatherElements(data, indices) -> (output)
  Attributes:
    axis = 0

Inputs:
  data: shape=(3, 3), dtype=float32
    [[1., 2., 3.],
     [4., 5., 6.],
     [7., 8., 9.]]
  indices: shape=(2, 3), dtype=int64
    [[-1, -2,  0],
     [-2,  0,  0]]

Outputs:
  output: shape=(2, 3), dtype=float32
    [[7., 5., 3.],
     [4., 2., 3.]]

Differences with previous version (11)

SchemaDiff: GatherElements (domain 'ai.onnx')

• old version: 11

• new version: 13

• breaking: no

Type constraints:

• changed ‘T’: added types: [‘tensor(bfloat16)’]

Documentation:

• line similarity: 0.42 (+30/-34 lines)

--- GatherElements v11
+++ GatherElements v13
@@ -11,47 +11,43 @@
 For instance, in the 3-D case (r = 3), the output produced is determined
 by the following equations:
 ```
-  out[i][j][k] = input[index[i][j][k]][j][k] if axis = 0,
-  out[i][j][k] = input[i][index[i][j][k]][k] if axis = 1,
-  out[i][j][k] = input[i][j][index[i][j][k]] if axis = 2,
+out[i][j][k] = input[index[i][j][k]][j][k] if axis = 0,
+out[i][j][k] = input[i][index[i][j][k]][k] if axis = 1,
+out[i][j][k] = input[i][j][index[i][j][k]] if axis = 2,
 ```

 This operator is also the inverse of ScatterElements. It is similar to Torch's gather operation.

 Example 1:
 ```
-  data = [
-      [1, 2],
-      [3, 4],
-  ]
-  indices = [
-      [0, 0],
-      [1, 0],
-  ]
-  axis = 1
-  output = [
-      [
-        [1, 1],
-        [4, 3],
-      ],
-  ]
+data = [
+    [1, 2],
+    [3, 4],
+]
+indices = [
+    [0, 0],
+    [1, 0],
+]
+axis = 1
+output = [
+    [1, 1],
+    [4, 3],
+]
 ```
 Example 2:
 ```
-  data = [
-      [1, 2, 3],
-      [4, 5, 6],
-      [7, 8, 9],
-  ]
-  indices = [
-      [1, 2, 0],
-      [2, 0, 0],
-  ]
-  axis = 0
-  output = [
-      [
-        [4, 8, 3],
-        [7, 2, 3],
-      ],
-  ]
+data = [
+    [1, 2, 3],
+    [4, 5, 6],
+    [7, 8, 9],
+]
+indices = [
+    [1, 2, 0],
+    [2, 0, 0],
+]
+axis = 0
+output = [
+    [4, 8, 3],
+    [7, 2, 3],
+]
 ```

Version History

• Version 11