.. _op_ai_onnx_AveragePool:

AveragePool
===========

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

AveragePool consumes an input tensor X and applies average pooling across
the tensor according to kernel sizes, stride sizes, and pad lengths.
average pooling consisting of computing the average on all values of a
subset of the input tensor according to the kernel size and downsampling the
data into the output tensor Y for further processing. The output spatial shape is calculated differently
depending on whether explicit padding is used, where pads is employed, or auto padding is used, where auto_pad is utilized.
With explicit padding (https://pytorch.org/docs/stable/generated/torch.nn.MaxPool2d.html?highlight=maxpool#torch.nn.MaxPool2d):

.. code-block::

    output_spatial_shape[i] = floor((input_spatial_shape[i] + pad_shape[i] - dilation[i] * (kernel_shape[i] - 1) - 1) / strides_spatial_shape[i] + 1)

or

.. code-block::

    output_spatial_shape[i] = ceil((input_spatial_shape[i] + pad_shape[i] - dilation[i] * (kernel_shape[i] - 1) - 1) / strides_spatial_shape[i] + 1)

if ceil_mode is enabled. ``pad_shape[i]`` is the sum of pads along axis ``i``. Sliding windows that would start in the right padded region are ignored.

``auto_pad`` is a DEPRECATED attribute. If you are using them currently, the output spatial shape will be following when ceil_mode is enabled:

.. code-block::

    VALID: output_spatial_shape[i] = ceil((input_spatial_shape[i] - ((kernel_spatial_shape[i] - 1) * dilations[i] + 1) + 1) / strides_spatial_shape[i])
    SAME_UPPER or SAME_LOWER: output_spatial_shape[i] = ceil(input_spatial_shape[i] / strides_spatial_shape[i])

or when ceil_mode is disabled (https://www.tensorflow.org/api_docs/python/tf/keras/layers/AveragePooling2D):

.. code-block::

    VALID: output_spatial_shape[i] = floor((input_spatial_shape[i] - ((kernel_spatial_shape[i] - 1) * dilations[i] + 1)) / strides_spatial_shape[i]) + 1
    SAME_UPPER or SAME_LOWER: output_spatial_shape[i] = floor((input_spatial_shape[i] - 1) / strides_spatial_shape[i]) + 1

And pad shape will be following if ``SAME_UPPER`` or ``SAME_LOWER``:

.. code-block::

    pad_shape[i] = (output_spatial_shape[i] - 1) * strides_spatial_shape[i] + ((kernel_spatial_shape[i] - 1) * dilations[i] + 1) - input_spatial_shape[i]

The output of each pooling window is divided by the number of elements (exclude pad when attribute count_include_pad is zero).

**Inputs**

- **X** (*T*): Input data tensor from the previous operator; dimensions for image case are (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 the width of the data. For non image case, the dimensions are in the form of (N x C x D1 x D2 ... Dn), where N is the batch size. Optionally, if dimension denotation is in effect, the operation expects the input data tensor to arrive with the dimension denotation of [DATA_BATCH, DATA_CHANNEL, DATA_FEATURE, DATA_FEATURE ...].

**Outputs**

- **Y** (*T*): Output data tensor from average or max pooling across the input tensor. Dimensions will vary based on various kernel, stride, and pad sizes. Floor value of the dimension is used

**Type Constraints**

- **T**: Constrain input and output types to float tensors.
  Allowed types: tensor(bfloat16), tensor(double), tensor(float), tensor(float16).

Differences with previous version (19)
--------------------------------------

**SchemaDiff**: ``AveragePool`` (domain ``'ai.onnx'``)

* old version: 19
* new version: 22
* breaking: no

**Type constraints:**

* changed 'T': added types: ['tensor(bfloat16)']

**Documentation:**

* line similarity: 0.97 (+1/-1 lines)

.. code-block:: diff

    --- AveragePool v19
    +++ AveragePool v22
    @@ -13,7 +13,7 @@
      ```
      output_spatial_shape[i] = ceil((input_spatial_shape[i] + pad_shape[i] - dilation[i] * (kernel_shape[i] - 1) - 1) / strides_spatial_shape[i] + 1)
      ```
    - if ceil_mode is enabled. `pad_shape[i]` is the sum of pads along axis `i`.
    + if ceil_mode is enabled. `pad_shape[i]` is the sum of pads along axis `i`. Sliding windows that would start in the right padded region are ignored.
     
      `auto_pad` is a DEPRECATED attribute. If you are using them currently, the output spatial shape will be following when ceil_mode is enabled:
      ```

Version History
---------------

- :doc:`Version 19 <AveragePool-19>`
- :doc:`Version 11 <AveragePool-11>`
- :doc:`Version 10 <AveragePool-10>`
- :doc:`Version 7 <AveragePool-7>`
- :doc:`Version 1 <AveragePool-1>`