GatherElements#

GatherElements - 13#

Version

  • name: GatherElements (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

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],
]

Attributes

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

Inputs

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

  • indices (heterogeneous) - 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 (heterogeneous) - T: Tensor of the same shape as indices.

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 integer types

Examples

gather_elements_0

axis = 1
node = onnx.helper.make_node(
    'GatherElements',
    inputs=['data', 'indices'],
    outputs=['y'],
    axis=axis,
)
data = np.array([[1, 2],
                 [3, 4]], dtype=np.float32)
indices = np.array([[0, 0],
                    [1, 0]], dtype=np.int32)

y = gather_elements(data, indices, axis)
# print(y) produces
# [[1, 1],
#  [4, 3]]

expect(node, inputs=[data, indices.astype(np.int64)], outputs=[y],
       name='test_gather_elements_0')

gather_elements_1

axis = 0
node = onnx.helper.make_node(
    'GatherElements',
    inputs=['data', 'indices'],
    outputs=['y'],
    axis=axis,
)
data = np.array([[1, 2, 3],
                 [4, 5, 6],
                 [7, 8, 9]], dtype=np.float32)
indices = np.array([[1, 2, 0],
                    [2, 0, 0]], dtype=np.int32)

y = gather_elements(data, indices, axis)
# print(y) produces
# [[4, 8, 3],
#  [7, 2, 3]]

expect(node, inputs=[data, indices.astype(np.int64)], outputs=[y],
       name='test_gather_elements_1')

gather_elements_negative_indices

axis = 0
node = onnx.helper.make_node(
    'GatherElements',
    inputs=['data', 'indices'],
    outputs=['y'],
    axis=axis,
)
data = np.array([[1, 2, 3],
                 [4, 5, 6],
                 [7, 8, 9]], dtype=np.float32)
indices = np.array([[-1, -2, 0],
                    [-2, 0, 0]], dtype=np.int32)

y = gather_elements(data, indices, axis)
# print(y) produces
# [[7, 5, 3],
#  [4, 2, 3]]

expect(node, inputs=[data, indices.astype(np.int64)], outputs=[y],
       name='test_gather_elements_negative_indices')

Differences

00GatherElements takes two inputs data and indices of the same rank r >= 1GatherElements takes two inputs data and indices of the same rank r >= 1
11and an optional attribute axis that identifies an axis of dataand an optional attribute axis that identifies an axis of data
22(by default, the outer-most axis, that is axis 0). It is an indexing operation(by default, the outer-most axis, that is axis 0). It is an indexing operation
33that produces its output by indexing into the input data tensor at indexthat produces its output by indexing into the input data tensor at index
44positions determined by elements of the indices tensor.positions determined by elements of the indices tensor.
55Its output shape is the same as the shape of indices and consists of one valueIts output shape is the same as the shape of indices and consists of one value
66(gathered from the data) for each element in indices.(gathered from the data) for each element in indices.
77
88For instance, in the 3-D case (r = 3), the output produced is determinedFor instance, in the 3-D case (r = 3), the output produced is determined
99by the following equations:by the following equations:
1010::::
1111
1212 out[i][j][k] = input[index[i][j][k]][j][k] if axis = 0, out[i][j][k] = input[index[i][j][k]][j][k] if axis = 0,
1313 out[i][j][k] = input[i][index[i][j][k]][k] if axis = 1, out[i][j][k] = input[i][index[i][j][k]][k] if axis = 1,
1414 out[i][j][k] = input[i][j][index[i][j][k]] if axis = 2, out[i][j][k] = input[i][j][index[i][j][k]] if axis = 2,
1515
1616This operator is also the inverse of ScatterElements. It is similar to Torch's gather operation.This operator is also the inverse of ScatterElements. It is similar to Torch's gather operation.
1717
1818Example 1:Example 1:
1919::::
2020
2121 data = [ data = [
2222 [1, 2], [1, 2],
2323 [3, 4], [3, 4],
2424 ] ]
2525 indices = [ indices = [
2626 [0, 0], [0, 0],
2727 [1, 0], [1, 0],
2828 ] ]
2929 axis = 1 axis = 1
3030 output = [ output = [
31 [
3231 [1, 1], [1, 1],
3332 [4, 3], [4, 3],
34 ],
3533 ] ]
3634
3735Example 2:Example 2:
3836::::
3937
4038 data = [ data = [
4139 [1, 2, 3], [1, 2, 3],
4240 [4, 5, 6], [4, 5, 6],
4341 [7, 8, 9], [7, 8, 9],
4442 ] ]
4543 indices = [ indices = [
4644 [1, 2, 0], [1, 2, 0],
4745 [2, 0, 0], [2, 0, 0],
4846 ] ]
4947 axis = 0 axis = 0
5048 output = [ output = [
51 [
5249 [4, 8, 3], [4, 8, 3],
5350 [7, 2, 3], [7, 2, 3],
54 ],
5551 ] ]
5652
5753**Attributes****Attributes**
5854
5955* **axis**:* **axis**:
6056 Which axis to gather on. Negative value means counting dimensions Which axis to gather on. Negative value means counting dimensions
6157 from the back. Accepted range is [-r, r-1] where r = rank(data). Default value is 0. from the back. Accepted range is [-r, r-1] where r = rank(data). Default value is 0.
6258
6359**Inputs****Inputs**
6460
6561* **data** (heterogeneous) - **T**:* **data** (heterogeneous) - **T**:
6662 Tensor of rank r >= 1. Tensor of rank r >= 1.
6763* **indices** (heterogeneous) - **Tind**:* **indices** (heterogeneous) - **Tind**:
6864 Tensor of int32/int64 indices, with the same rank r as the input. Tensor of int32/int64 indices, with the same rank r as the input.
6965 All index values are expected to be within bounds [-s, s-1] along All index values are expected to be within bounds [-s, s-1] along
7066 axis of size s. It is an error if any of the index values are out of axis of size s. It is an error if any of the index values are out of
7167 bounds. bounds.
7268
7369**Outputs****Outputs**
7470
7571* **output** (heterogeneous) - **T**:* **output** (heterogeneous) - **T**:
7672 Tensor of the same shape as indices. Tensor of the same shape as indices.
7773
7874**Type Constraints****Type Constraints**
7975
8076* **T** in (* **T** in (
77 tensor(bfloat16),
8178 tensor(bool), tensor(bool),
8279 tensor(complex128), tensor(complex128),
8380 tensor(complex64), tensor(complex64),
8481 tensor(double), tensor(double),
8582 tensor(float), tensor(float),
8683 tensor(float16), tensor(float16),
8784 tensor(int16), tensor(int16),
8885 tensor(int32), tensor(int32),
8986 tensor(int64), tensor(int64),
9087 tensor(int8), tensor(int8),
9188 tensor(string), tensor(string),
9289 tensor(uint16), tensor(uint16),
9390 tensor(uint32), tensor(uint32),
9491 tensor(uint64), tensor(uint64),
9592 tensor(uint8) tensor(uint8)
9693 ): ):
9794 Constrain input and output types to any tensor type. Constrain input and output types to any tensor type.
9895* **Tind** in (* **Tind** in (
9996 tensor(int32), tensor(int32),
10097 tensor(int64) tensor(int64)
10198 ): ):
10299 Constrain indices to integer types Constrain indices to integer types

GatherElements - 11#

Version

  • name: GatherElements (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

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],
    ],
]

Attributes

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

Inputs

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

  • indices (heterogeneous) - 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 (heterogeneous) - T: Tensor of the same shape as indices.

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.

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