.. _l-onnx-doc-Gather: ====== Gather ====== .. contents:: :local: .. _l-onnx-op-gather-13: Gather - 13 =========== **Version** * **name**: `Gather (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, and `indices` tensor of rank q, gather entries of the axis dimension of `data` (by default outer-most one as axis=0) indexed by `indices`, and concatenates them in an output tensor of rank q + (r - 1). axis = 0 : Let k = indices[i_{0}, ..., i_{q-1}] Then output[i_{0}, ..., i_{q-1}, j_{0}, ..., j_{r-2}] = input[k , j_{0}, ..., j_{r-2}] :: data = [ [1.0, 1.2], [2.3, 3.4], [4.5, 5.7], ] indices = [ [0, 1], [1, 2], ] output = [ [ [1.0, 1.2], [2.3, 3.4], ], [ [2.3, 3.4], [4.5, 5.7], ], ] axis = 1 : Let k = indices[i_{0}, ..., i_{q-1}] Then output[j_{0}, i_{0}, ..., i_{q-1}, j_{1}, ..., j_{r-2}] = input[j_{0}, k, j_{1}, ..., j_{r-2}] :: data = [ [1.0, 1.2, 1.9], [2.3, 3.4, 3.9], [4.5, 5.7, 5.9], ] indices = [ [0, 2], ] axis = 1, output = [ [[1.0, 1.9]], [[2.3, 3.9]], [[4.5, 5.9]], ] **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, of any rank q. 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 - 1). **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_0** :: node = onnx.helper.make_node( "Gather", inputs=["data", "indices"], outputs=["y"], axis=0, ) data = np.random.randn(5, 4, 3, 2).astype(np.float32) indices = np.array([0, 1, 3]) y = np.take(data, indices, axis=0) expect( node, inputs=[data, indices.astype(np.int64)], outputs=[y], name="test_gather_0", ) **_gather_1** :: node = onnx.helper.make_node( "Gather", inputs=["data", "indices"], outputs=["y"], axis=1, ) data = np.random.randn(5, 4, 3, 2).astype(np.float32) indices = np.array([0, 1, 3]) y = np.take(data, indices, axis=1) expect( node, inputs=[data, indices.astype(np.int64)], outputs=[y], name="test_gather_1", ) **_gather_2d_indices** :: node = onnx.helper.make_node( "Gather", inputs=["data", "indices"], outputs=["y"], axis=1, ) data = np.random.randn(3, 3).astype(np.float32) indices = np.array([[0, 2]]) y = np.take(data, indices, axis=1) expect( node, inputs=[data, indices.astype(np.int64)], outputs=[y], name="test_gather_2d_indices", ) **_gather_negative_indices** :: node = onnx.helper.make_node( "Gather", inputs=["data", "indices"], outputs=["y"], axis=0, ) data = np.arange(10).astype(np.float32) indices = np.array([0, -9, -10]) y = np.take(data, indices, axis=0) # print(y) # [0. 1. 0.] expect( node, inputs=[data, indices.astype(np.int64)], outputs=[y], name="test_gather_negative_indices", ) **Differences** .. raw:: html
00Given data tensor of rank r >= 1, and indices tensor of rank q, gatherGiven data tensor of rank r >= 1, and indices tensor of rank q, gather
11entries of the axis dimension of data (by default outer-most one as axis=0) indexed by indices, and concatenatesentries of the axis dimension of data (by default outer-most one as axis=0) indexed by indices, and concatenates
22them in an output tensor of rank q + (r - 1).them in an output tensor of rank q + (r - 1).
33
44axis = 0 :axis = 0 :
55
66LetLet
77k = indices[i_{0}, ..., i_{q-1}]k = indices[i_{0}, ..., i_{q-1}]
88ThenThen
99output[i_{0}, ..., i_{q-1}, j_{0}, ..., j_{r-2}] = input[k , j_{0}, ..., j_{r-2}]output[i_{0}, ..., i_{q-1}, j_{0}, ..., j_{r-2}] = input[k , j_{0}, ..., j_{r-2}]
1010
1111::::
1212
1313 data = [ data = [
1414 [1.0, 1.2], [1.0, 1.2],
1515 [2.3, 3.4], [2.3, 3.4],
1616 [4.5, 5.7], [4.5, 5.7],
1717 ] ]
1818 indices = [ indices = [
1919 [0, 1], [0, 1],
2020 [1, 2], [1, 2],
2121 ] ]
2222 output = [ output = [
2323 [ [
2424 [1.0, 1.2], [1.0, 1.2],
2525 [2.3, 3.4], [2.3, 3.4],
2626 ], ],
2727 [ [
2828 [2.3, 3.4], [2.3, 3.4],
2929 [4.5, 5.7], [4.5, 5.7],
3030 ], ],
3131 ] ]
3232
3333axis = 1 :axis = 1 :
3434
3535LetLet
3636k = indices[i_{0}, ..., i_{q-1}]k = indices[i_{0}, ..., i_{q-1}]
3737ThenThen
3838output[i_{0}, ..., i_{q-1}, j_{0}, ..., j_{r-2}] = input[j_{0}, k, j_{1}, ..., j_{r-2}]output[j_{0}, i_{0}, ..., i_{q-1}, j_{1}, ..., j_{r-2}] = input[j_{0}, k, j_{1}, ..., j_{r-2}]
3939
4040::::
4141
4242 data = [ data = [
4343 [1.0, 1.2, 1.9], [1.0, 1.2, 1.9],
4444 [2.3, 3.4, 3.9], [2.3, 3.4, 3.9],
4545 [4.5, 5.7, 5.9], [4.5, 5.7, 5.9],
4646 ] ]
4747 indices = [ indices = [
4848 [0, 2], [0, 2],
4949 ] ]
5050 axis = 1, axis = 1,
5151 output = [ output = [
52 [
5352 [1.0, 1.9], [[1.0, 1.9]],
5453 [2.3, 3.9], [[2.3, 3.9]],
5554 [4.5, 5.9], [[4.5, 5.9]],
56 ],
5755 ] ]
5856
5957**Attributes****Attributes**
6058
6159* **axis**:* **axis**:
6260 Which axis to gather on. Negative value means counting dimensions Which axis to gather on. Negative value means counting dimensions
6361 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.
6462
6563**Inputs****Inputs**
6664
6765* **data** (heterogeneous) - **T**:* **data** (heterogeneous) - **T**:
6866 Tensor of rank r >= 1. Tensor of rank r >= 1.
6967* **indices** (heterogeneous) - **Tind**:* **indices** (heterogeneous) - **Tind**:
7068 Tensor of int32/int64 indices, of any rank q. All index values are Tensor of int32/int64 indices, of any rank q. All index values are
7169 expected to be within bounds [-s, s-1] along axis of size s. It is expected to be within bounds [-s, s-1] along axis of size s. It is
7270 an error if any of the index values are out of bounds. an error if any of the index values are out of bounds.
7371
7472**Outputs****Outputs**
7573
7674* **output** (heterogeneous) - **T**:* **output** (heterogeneous) - **T**:
7775 Tensor of rank q + (r - 1). Tensor of rank q + (r - 1).
7876
7977**Type Constraints****Type Constraints**
8078
8179* **T** in (* **T** in (
80 tensor(bfloat16),
8281 tensor(bool), tensor(bool),
8382 tensor(complex128), tensor(complex128),
8483 tensor(complex64), tensor(complex64),
8584 tensor(double), tensor(double),
8685 tensor(float), tensor(float),
8786 tensor(float16), tensor(float16),
8887 tensor(int16), tensor(int16),
8988 tensor(int32), tensor(int32),
9089 tensor(int64), tensor(int64),
9190 tensor(int8), tensor(int8),
9291 tensor(string), tensor(string),
9392 tensor(uint16), tensor(uint16),
9493 tensor(uint32), tensor(uint32),
9594 tensor(uint64), tensor(uint64),
9695 tensor(uint8) tensor(uint8)
9796 ): ):
9897 Constrain input and output types to any tensor type. Constrain input and output types to any tensor type.
9998* **Tind** in (* **Tind** in (
10099 tensor(int32), tensor(int32),
101100 tensor(int64) tensor(int64)
102101 ): ):
103102 Constrain indices to integer types Constrain indices to integer types
.. _l-onnx-op-gather-11: Gather - 11 =========== **Version** * **name**: `Gather (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, gather entries of the axis dimension of `data` (by default outer-most one as axis=0) indexed by `indices`, and concatenates them in an output tensor of rank q + (r - 1). axis = 0 : Let k = indices[i_{0}, ..., i_{q-1}] Then output[i_{0}, ..., i_{q-1}, j_{0}, ..., j_{r-2}] = input[k , j_{0}, ..., j_{r-2}] :: data = [ [1.0, 1.2], [2.3, 3.4], [4.5, 5.7], ] indices = [ [0, 1], [1, 2], ] output = [ [ [1.0, 1.2], [2.3, 3.4], ], [ [2.3, 3.4], [4.5, 5.7], ], ] axis = 1 : Let k = indices[i_{0}, ..., i_{q-1}] Then output[i_{0}, ..., i_{q-1}, j_{0}, ..., j_{r-2}] = input[j_{0}, k, j_{1}, ..., j_{r-2}] :: data = [ [1.0, 1.2, 1.9], [2.3, 3.4, 3.9], [4.5, 5.7, 5.9], ] indices = [ [0, 2], ] axis = 1, output = [ [ [1.0, 1.9], [2.3, 3.9], [4.5, 5.9], ], ] **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, of any rank q. 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 - 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. * **Tind** in ( tensor(int32), tensor(int64) ): Constrain indices to integer types **Differences** .. raw:: html
00Given data tensor of rank r >= 1, and indices tensor of rank q, gatherGiven data tensor of rank r >= 1, and indices tensor of rank q, gather
11entries of the axis dimension of data (by default outer-most one as axis=0) indexed by indices, and concatenatesentries of the axis dimension of data (by default outer-most one as axis=0) indexed by indices, and concatenates
22them in an output tensor of rank q + (r - 1).them in an output tensor of rank q + (r - 1).
3
4axis = 0 :
5
6Let
37Example 1:k = indices[i_{0}, ..., i_{q-1}]
8Then
9output[i_{0}, ..., i_{q-1}, j_{0}, ..., j_{r-2}] = input[k , j_{0}, ..., j_{r-2}]
10
411::::
512
613 data = [ data = [
714 [1.0, 1.2], [1.0, 1.2],
815 [2.3, 3.4], [2.3, 3.4],
916 [4.5, 5.7], [4.5, 5.7],
1017 ] ]
1118 indices = [ indices = [
1219 [0, 1], [0, 1],
1320 [1, 2], [1, 2],
1421 ] ]
1522 output = [ output = [
1623 [ [
1724 [1.0, 1.2], [1.0, 1.2],
1825 [2.3, 3.4], [2.3, 3.4],
1926 ], ],
2027 [ [
2128 [2.3, 3.4], [2.3, 3.4],
29 [4.5, 5.7],
30 ],
31 ]
32
33axis = 1 :
34
35Let
2236 [4.5, 5.7],k = indices[i_{0}, ..., i_{q-1}]
23 ],
24 ]
25
37Then
2638Example 2:output[i_{0}, ..., i_{q-1}, j_{0}, ..., j_{r-2}] = input[j_{0}, k, j_{1}, ..., j_{r-2}]
39
2740::::
2841
2942 data = [ data = [
3043 [1.0, 1.2, 1.9], [1.0, 1.2, 1.9],
3144 [2.3, 3.4, 3.9], [2.3, 3.4, 3.9],
3245 [4.5, 5.7, 5.9], [4.5, 5.7, 5.9],
3346 ] ]
3447 indices = [ indices = [
3548 [0, 2], [0, 2],
3649 ] ]
3750 axis = 1, axis = 1,
3851 output = [ output = [
3952 [ [
4053 [1.0, 1.9], [1.0, 1.9],
4154 [2.3, 3.9], [2.3, 3.9],
4255 [4.5, 5.9], [4.5, 5.9],
4356 ], ],
4457 ] ]
4558
4659**Attributes****Attributes**
4760
4861* **axis**:* **axis**:
4962 Which axis to gather on. Negative value means counting dimensions Which axis to gather on. Negative value means counting dimensions
5063 from the back. Accepted range is [-r, r-1] Default value is 0. from the back. Accepted range is [-r, r-1] where r = rank(data). Default value is 0.
5164
5265**Inputs****Inputs**
5366
5467* **data** (heterogeneous) - **T**:* **data** (heterogeneous) - **T**:
5568 Tensor of rank r >= 1. Tensor of rank r >= 1.
5669* **indices** (heterogeneous) - **Tind**:* **indices** (heterogeneous) - **Tind**:
5770 Tensor of int32/int64 indices, of any rank q. All index values are Tensor of int32/int64 indices, of any rank q. All index values are
5871 expected to be within bounds. It is an error if any of the index expected to be within bounds [-s, s-1] along axis of size s. It is
5972 values are out of bounds. an error if any of the index values are out of bounds.
6073
6174**Outputs****Outputs**
6275
6376* **output** (heterogeneous) - **T**:* **output** (heterogeneous) - **T**:
6477 Tensor of rank q + (r - 1). Tensor of rank q + (r - 1).
6578
6679**Type Constraints****Type Constraints**
6780
6881* **T** in (* **T** in (
6982 tensor(bool), tensor(bool),
7083 tensor(complex128), tensor(complex128),
7184 tensor(complex64), tensor(complex64),
7285 tensor(double), tensor(double),
7386 tensor(float), tensor(float),
7487 tensor(float16), tensor(float16),
7588 tensor(int16), tensor(int16),
7689 tensor(int32), tensor(int32),
7790 tensor(int64), tensor(int64),
7891 tensor(int8), tensor(int8),
7992 tensor(string), tensor(string),
8093 tensor(uint16), tensor(uint16),
8194 tensor(uint32), tensor(uint32),
8295 tensor(uint64), tensor(uint64),
8396 tensor(uint8) tensor(uint8)
8497 ): ):
8598 Constrain input and output types to any tensor type. Constrain input and output types to any tensor type.
8699* **Tind** in (* **Tind** in (
87100 tensor(int32), tensor(int32),
88101 tensor(int64) tensor(int64)
89102 ): ):
90103 Constrain indices to integer types Constrain indices to integer types
.. _l-onnx-op-gather-1: Gather - 1 ========== **Version** * **name**: `Gather (GitHub) `_ * **domain**: **main** * **since_version**: **1** * **function**: False * **support_level**: SupportType.COMMON * **shape inference**: True This version of the operator has been available **since version 1**. **Summary** Given `data` tensor of rank r >= 1, and `indices` tensor of rank q, gather entries of the axis dimension of `data` (by default outer-most one as axis=0) indexed by `indices`, and concatenates them in an output tensor of rank q + (r - 1). Example 1: :: data = [ [1.0, 1.2], [2.3, 3.4], [4.5, 5.7], ] indices = [ [0, 1], [1, 2], ] output = [ [ [1.0, 1.2], [2.3, 3.4], ], [ [2.3, 3.4], [4.5, 5.7], ], ] Example 2: :: data = [ [1.0, 1.2, 1.9], [2.3, 3.4, 3.9], [4.5, 5.7, 5.9], ] indices = [ [0, 2], ] axis = 1, output = [ [ [1.0, 1.9], [2.3, 3.9], [4.5, 5.9], ], ] **Attributes** * **axis**: Which axis to gather on. Negative value means counting dimensions from the back. Accepted range is [-r, r-1] Default value is ``0``. **Inputs** * **data** (heterogeneous) - **T**: Tensor of rank r >= 1. * **indices** (heterogeneous) - **Tind**: Tensor of int32/int64 indices, of any rank q. All index values are expected to be within bounds. It is an error if any of the index values are out of bounds. **Outputs** * **output** (heterogeneous) - **T**: Tensor of rank q + (r - 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. * **Tind** in ( tensor(int32), tensor(int64) ): Constrain indices to integer types