mindspore.nn.AvgPool3d

class mindspore.nn.AvgPool3d(kernel_size=1, stride=1, pad_mode='valid', padding=0, ceil_mode=False, count_include_pad=True, divisor_override=None)[source]

Applies a 3D average pooling over an input Tensor which can be regarded as a composition of 3D input planes. Typically, the input is of shape \((N_{in}, C_{in}, D_{in}, H_{in}, W_{in})\), and AvgPool3D outputs regional average in the \((D_{in}, H_{in}, W_{in})\)-dimension. Given kernel size is \(ks = (d_{ker}, h_{ker}, w_{ker})\) and stride \(s = (s_0, s_1, s_2)\), the operation is as follows.

Warning

kernel_size is in the range [1, 255]. stride is in the range [1, 63].

\[\text{output}(N_i, C_j, d, h, w) = \frac{1}{d_{ker} * h_{ker} * w_{ker}} \sum_{l=0}^{d_{ker}-1} \sum_{m=0}^{h_{ker}-1} \sum_{n=0}^{w_{ker}-1} \text{input}(N_i, C_j, s_0 \times d + l, s_1 \times h + m, s_2 \times w + n)\]
Parameters

  • kernel_size (Union[int, tuple[int]], optional) – The size of kernel used to take the average value, can be an int number or a single element tuple that represents depth, height and width, or a tuple of three positive integers that represent depth, height and width respectively. Default: 1 .

  • stride (Union[int, tuple[int]], optional) – The distance of kernel moving, can be a positive int or a single element tuple that represents the depth, height and width of movement, or a tuple of three positive integers that represents depth, height and width of movement respectively. If the value is None, the default value kernel_size is used. Default: 1 .

  • pad_mode (str, optional) –

    Specifies the padding method of pooling, optional values are "same", "valid" or "pad" , case insensitive. Default: "valid" .

    • same: The depth, height and width of the output is the same as the value after the input is divided by stride.

    • valid: Returns the output obtained by effective calculation without padding. The excess pixels that do not meet the calculation will be discarded.

    • pad: Pads the input. Fill the front, back, top, and bottom of the input with 0s of size padding. If this mode is set, padding must be greater than or equal to 0.

  • padding (Union(int, tuple[int], list[int]), optional) –

    Pooling padding value, only ‘pad’ mode can be set to non-zero. Default: 0 . Only the following paddings are supported:

    • padding is an integer or a tuple/list containing one integer, it will be padded in six directions of front, back, top, bottom, left and right of the input.

    • padding is a tuple/list containing three integers, it will be padded in front and back of the input padding[0] times, up and down padding[1] times, and left and right of the input padding[2] times.

  • ceil_mode (bool, optional) – If True , use ceil to compute the output shape instead of floor. Default: False .

  • count_include_pad (bool, optional) – If True , averaging calculation will include the zero-padding. Default: True .

  • divisor_override (int, optional) – If it is specified as a non-zero parameter, this parameter will be used as the divisor in the average calculation. Otherwise, kernel_size will be used as the divisor. Default: None .

Inputs:

  • x (Tensor) - Tensor of shape \((N, C, D_{in}, H_{in}, W_{in})\) or \((C, D_{in}, H_{in}, W_{in})\). Currently support float16, float32 and float64 data type.

Outputs:

Tensor, with shape \((N, C, D_{out}, H_{out}, W_{out})\) or \((C, D_{out}, H_{out}, W_{out})\), with the same data type as x.

If pad_mode is in pad mode, the output shape calculation formula is as follows:

\[D_{out} = \left\lfloor\frac{D_{in} + 2 \times \text{padding}[0] - \text{kernel_size}[0]}{\text{stride}[0]} + 1\right\rfloor\]
\[H_{out} = \left\lfloor\frac{H_{in} + 2 \times \text{padding}[1] - \text{kernel_size}[1]}{\text{stride}[1]} + 1\right\rfloor\]
\[W_{out} = \left\lfloor\frac{W_{in} + 2 \times \text{padding}[2] - \text{kernel_size}[2]}{\text{stride}[2]} + 1\right\rfloor\]
Raises

  • TypeError – If kernel_size is neither an int nor a tuple.

  • TypeError – If stride is neither an int nor a tuple.

  • TypeError – If padding is neither an int nor a tuple/list.

  • TypeError – If ceil_mode or count_include_pad is not a bool.

  • TypeError – If divisor_override is not an int.

  • ValueError – If numbers in kernel_size or stride are not positive.

  • ValueError – If kernel_size or stride is a tuple whose length is not equal to 3.

  • ValueError – If padding is a tuple/list whose length is neither 1 nor 3.

  • ValueError – If element of padding is less than 0.

  • ValueError – If length of shape of x is neither 4 nor 5.

  • ValueError – If divisor_override is less than or equal to 0.

  • ValueError – If padding is non-zero when pad_mode is not ‘pad’.

Supported Platforms:

Ascend GPU CPU

Examples

>>> import mindspore as ms
>>> pool = ms.nn.AvgPool3d(kernel_size=3, stride=1)
>>> x = ms.ops.randn(1, 2, 4, 4, 5).astype(ms.float32)
>>> output = pool(x)
>>> print(output.shape)
(1, 2, 2, 2, 3)
>>> x1 = ms.ops.randn(6, 5, 7, 7, 5).astype(ms.float32)
>>> pool2 = ms.nn.AvgPool3d(4, stride=2, pad_mode='pad', padding=(2, 2, 1), divisor_override=10)
>>> output2 = pool2(x1)
>>> print(output2.shape)
(6, 5, 4, 4, 2)