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 mode with a padding value of 0. It can be set to: "same" , "valid" or "pad" . Default: "valid" .

    • "same": Pad the input around its depth/height/width dimension so that the shape of input and output are the same when stride is set to 1. The amount of padding to is calculated by the operator internally. If the amount is even, it isuniformly distributed around the input, if it is odd, the excess amount goes to the front/right/bottom side. If this mode is set, padding must be 0.

    • "valid": No padding is applied to the input, and the output returns the maximum possible depth, height and width. Extra pixels that could not complete a full stride will be discarded. If this mode is set, padding must be 0.

    • "pad": Pad the input with a specified amount. In this mode, the amount of padding in the depth, height and width dimension is determined by the padding parameter. 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)