.. _op_ai_onnx_ConvInteger:

ConvInteger
===========

- **Domain**: ``ai.onnx``
- **Since version**: 10

The integer convolution operator consumes an input tensor, its zero-point, a filter, and its zero-point,
and computes the output. The production MUST never overflow. The accumulation may overflow if and only if in 32 bits.

**Inputs**

- **x** (*T1*): Input data tensor from previous layer; has size (N x C x H x W), where N is the batch size, C is the number of channels, and H and W are the height and width. Note that this is for the 2D image. Otherwise the size is (N x C x D1 x D2 ... x Dn). Optionally, if dimension denotation is in effect, the operation expects input data tensor to arrive with the dimension denotation of [DATA_BATCH, DATA_CHANNEL, DATA_FEATURE, DATA_FEATURE ...].
- **w** (*T2*): The weight tensor that will be used in the convolutions; has size (M x C/group x kH x kW), where C is the number of channels, and kH and kW are the height and width of the kernel, and M is the number of feature maps. For more than 2 dimensions, the kernel shape will be (M x C/group x k1 x k2 x ... x kn), where (k1 x k2 x ... kn) is the dimension of the kernel. Optionally, if dimension denotation is in effect, the operation expects the weight tensor to arrive with the dimension denotation of [FILTER_OUT_CHANNEL, FILTER_IN_CHANNEL, FILTER_SPATIAL, FILTER_SPATIAL ...]. X.shape[1] == (W.shape[1] \* group) == C (assuming zero based indices for the shape array). Or in other words FILTER_IN_CHANNEL should be equal to DATA_CHANNEL.
- **x_zero_point** (*T1*): Zero point tensor for input 'x'. It's optional and default value is 0. It's a scalar, which means a per-tensor/layer quantization.
- **w_zero_point** (*T2*): Zero point tensor for input 'w'. It's optional and default value is 0.  It could be a scalar or a 1-D tensor, which means a per-tensor/layer or per output channel quantization. If it's a 1-D tensor, its number of elements should be equal to the number of output channels (M)

**Outputs**

- **y** (*T3*): Output data tensor that contains the result of the convolution. The output dimensions are functions of the kernel size, stride size, and pad lengths.

**Type Constraints**

- **T1**: Constrain input x and its zero point data type to 8-bit integer tensor.
  Allowed types: tensor(int8), tensor(uint8).
- **T2**: Constrain input w and its zero point data type to 8-bit integer tensor.
  Allowed types: tensor(int8), tensor(uint8).
- **T3**: Constrain output y data type to 32-bit integer tensor.
  Allowed types: tensor(int32).

Examples
--------

**test_cc_basic_convinteger**

.. code-block:: text

    Node:
      ConvInteger(X, W, x_zero_point) -> (Y)
      Attributes:
        kernel_shape = [2, 2]

.. code-block:: text

    Inputs:
      X: shape=(1, 1, 3, 3), dtype=uint8
        [[[[ 2,  3,  4],
           [ 5,  6,  7],
           [ 8,  9, 10]]]]
      W: shape=(1, 1, 2, 2), dtype=uint8
        [[[[1, 1],
           [1, 1]]]]
      x_zero_point: shape=(), dtype=uint8
        1

    Outputs:
      Y: shape=(1, 1, 2, 2), dtype=int32
        [[[[12, 16],
           [24, 28]]]]

**test_cc_convinteger_with_padding**

.. code-block:: text

    Node:
      ConvInteger(X, W, x_zero_point) -> (Y)
      Attributes:
        kernel_shape = [2, 2]
        pads = [1, 1, 1, 1]

.. code-block:: text

    Inputs:
      X: shape=(1, 1, 3, 3), dtype=uint8
        [[[[ 2,  3,  4],
           [ 5,  6,  7],
           [ 8,  9, 10]]]]
      W: shape=(1, 1, 2, 2), dtype=uint8
        [[[[1, 1],
           [1, 1]]]]
      x_zero_point: shape=(), dtype=uint8
        1

    Outputs:
      Y: shape=(1, 1, 4, 4), dtype=int32
        [[[[ 1,  3,  5,  3],
           [ 5, 12, 16,  9],
           [11, 24, 28, 15],
           [ 7, 15, 17,  9]]]]

**test_cc_convinteger_without_padding**

.. code-block:: text

    Node:
      ConvInteger(X, W, x_zero_point) -> (Y)

.. code-block:: text

    Inputs:
      X: shape=(1, 1, 3, 3), dtype=uint8
        [[[[ 2,  3,  4],
           [ 5,  6,  7],
           [ 8,  9, 10]]]]
      W: shape=(1, 1, 2, 2), dtype=uint8
        [[[[1, 1],
           [1, 1]]]]
      x_zero_point: shape=(), dtype=uint8
        1

    Outputs:
      Y: shape=(1, 1, 2, 2), dtype=int32
        [[[[12, 16],
           [24, 28]]]]