.. _op_ai_onnx_GatherElements:

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:

.. code-block::

    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:

.. code-block::

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

Example 2:

.. code-block::

    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**

.. code-block:: text

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

.. code-block:: text

    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**

.. code-block:: text

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

.. code-block:: text

    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**

.. code-block:: text

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

.. code-block:: text

    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)

.. code-block:: diff

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

- :doc:`Version 11 <GatherElements-11>`