aclnnAvgPool2dBackward

Applicable Products

Applicable Products	Supported
Ascend 950PR/Ascend 950DT	√
Atlas A3 training products/Atlas A3 inference products	√
Atlas A2 training products/Atlas A2 inference products	√
Atlas 200I/500 A2 inference products	×
Atlas inference products	√
Atlas training products	√

Function

Description: Backward propagation of 2D average pooling. Computes the gradient of the input for the forward propagation of 2D average pooling.
Formula: Assume that the input tensor of the 2D average pooling forward pass is $X$ , the output tensor is $Y$ , the kernel size is $k*k$ , and the stride is $s$ . Then the gradient of $X$ , $\frac{\partial L}{\partial X}$ , is calculated as follows:
$\frac{\partial L}{\partial X_{i,j}}=\frac{1}{k^2}\sum_{n=0}^{k-1}\frac{\partial L}{\partial Y_{\lfloor\frac{i*s+m}{k}\rfloor,\lfloor\frac{j*s+n}{k}\rfloor}}$
The parameters are described as follows:
- $L$ is the loss function, and $\lfloor\cdot\rfloor$ indicates rounding up.
- $X_{i,j}$ represents the $i$ -th row and $j$ -th column of the input feature map.
- $Y_{\lfloor\frac{i*s+m}{k}\rfloor,\lfloor\frac{j*s+n}{k}\rfloor}$ represents the pixel value at the $\lfloor\frac{i*s+m}{k}\rfloor$ -th row and $\lfloor\frac{j*s+n}{k}\rfloor$ -th column of the output feature map.
- $k$ represents the kernel size of the pooling window.
- $s$ represents the stride size.
- $\frac{\partial L}{\partial X_{i,j}}$ represents the partial derivative of the loss function $L$ with respect to the pixel value at row $i$ , column $j$ in the input feature map.
- $\frac{\partial L}{\partial Y_{\lfloor\frac{i*s+m}{k}\rfloor,\lfloor\frac{j*s+n}{k}\rfloor}}$ represents the partial derivative of the loss function $L$ with respect to the pixel value at row $\lfloor\frac{i*s+m}{k}\rfloor$ , column $\lfloor\frac{j*s+n}{k}\rfloor$ in the output feature map.

Function Prototype

Each operator is divided into a two-phase API. You must first call the "aclnnAvgPool2dBackwardGetWorkspaceSize" API to obtain the workspace size required for computation and the executor that contains the operator computation process, and then call the "aclnnAvgPool2dBackward" API to perform the computation.

aclnnStatus aclnnAvgPool2dBackwardGetWorkspaceSize(
  const aclTensor   *gradOutput,
  const aclTensor   *self,
  const aclIntArray *kernelSize,
  const aclIntArray *stride,
  const aclIntArray *padding,
  bool               ceilMode,
  bool               countIncludePad,
  int64_t            divisorOverride,
  int8_t             cubeMathType,
  aclTensor         *gradInput,
  uint64_t          *workspaceSize,
  aclOpExecutor     **executor)

aclnnStatus aclnnAvgPool2dBackward(
  void          *workspace,
  uint64_t       workspaceSize,
  aclOpExecutor *executor,
  aclrtStream    stream)

aclnnAvgPool2dBackwardGetWorkspaceSize

Parameters:

Parameter	Input/Output	Description	Instruction	Data Type	Data Format	Shape	Non-contiguous Tensor
gradOutput	Input	Represents the input gradient.	Empty tensors are not supported.	FLOAT32, FLOAT16, BFLOAT16	NCHW, NCL	3-4	√
self	Input	Input of the forward process.	Empty tensors are not supported.	FLOAT32, FLOAT16, BFLOAT16	NCHW, NCL	3-4	√
kernelSize	Input	Size of the pooling window, denoted as k in the formula.	Length of 1 (kH = kW) or 2 (kH, kW), with values greater than 0.	INT64	-	-	-
stride	Input	Stride of the pooling operation, i.e., strides in the formula.	Length of 1 (sH=sW) or 2 (sH, sW). The value must be greater than 0.	INT64	-	-	-
padding	Input	Number of zero-padding layers in the H and W dimensions of the input, i.e., paddings in the formula.	Length of 1 (padH = padW) or 2 (padH, padW). The value cannot be less than 0.	INT64	-	-	-
ceilMode	Input	Whether the shape of the derived output out is rounded up.	-	BOOL	-	-	-
countIncludePad	Input	Whether to include padding zeros when computing average pooling.	-	BOOL	-	-	-
divisorOverride	Input	Divisor for averaging.	Atlas inference products and Atlas training products: The supported range is [-255, 255]. 0 indicates that padding does not affect the average calculation.	INT64	-	-	-
cubeMathType	Input	Specifies the computation logic of the Cube unit.	-	INT8	-	-	-
gradInput	Output	Output tensor, i.e., out in the formula.	-	FLOAT32, FLOAT16, BFLOAT16	NCHW, NCL	3-4	√
workspaceSize	Output	Returns the workspace size to be applied for on the Device side.	-	-	-	-	-
executor	Output	Returns the operator executor, which contains the operator computation flow.	-	-	-	-	-

Atlas inference products, Atlas training products: The data types of the self and out parameters do not support BFLOAT16.

cubeMathType: The supported enumeration values are as follows:

0: KEEP_DTYPE, which keeps the input data type for computation.
- Atlas training products, Atlas inference products: This option is not supported when the input data type is FLOAT32.
1: ALLOW_FP32_DOWN_PRECISION, which allows the input data to be computed at reduced precision.
- Atlas training products, Atlas inference products: When the input data type is FLOAT32, it is converted to FLOAT16 for computation. No processing is performed for other input data types.
- Atlas A2 training products/Atlas A2 inference products, Atlas A3 training products/Atlas A3 inference products: When the input data type is FLOAT32, it is converted to HFLOAT32 for computation. No processing is performed for other input data types.
- Ascend 950PR/Ascend 950DT: In globalPooling mode, when the input data type is FLOAT32, it is converted to HFLOAT32 for computation. No processing is performed for other input data types.
2: USE_FP16, supports downscaling the input precision to FLOAT16 for computation.
- Atlas A2 training products/Atlas A2 inference products, Atlas A3 training products/Atlas A3 inference products: This option is not supported when the input data type is BFLOAT16.
- Ascend 950PR/Ascend 950DT: In globalPooling mode, this option is not supported when the input data type is BFLOAT16.
3: USE_HF32, supports reducing input precision to HFLOAT32 for computation.
- Atlas training products, Atlas inference products: This option is not supported.
- Atlas A2 training products/Atlas A2 inference products, Atlas A3 training products/Atlas A3 inference products : When the input data type is FLOAT32, it is converted to HFLOAT32 for computation. This option is not supported for other input data types.
- Ascend 950PR/Ascend 950DT: In globalPooling mode, when the input data type is FLOAT32, it is converted to HFLOAT32 for computation. This option is not supported for other input data types.

Return value:

aclnnStatus: return code. For details, see aclnn Return Code.

The first-phase API performs input parameter validation and returns an error in the following scenarios:

Return Code	Error Code	Description
ACLNN_ERR_PARAM_NULLPTR	161001	The passed gradOutput, self, kernelSize, padding, or gradInput is a null pointer.
ACLNN_ERR_PARAM_INVALID	161002	The data type or data format of the passed gradOutput or gradInput is not within the supported range.
		The data type or data format of the passed self and gradInput is inconsistent.
		The dimension of the input gradOutput, self, kernelSize, stride, or gradInput is not within the supported range.
		A dimension value of the input gradOutput, self, kernelSize, stride, or gradInput is less than 0.
		The input cubeMathType is not within the supported range.
		The padding attribute exceeds 1/2 of the corresponding kernelSize dimension. For example, if paddingH = 2 and kernelSizeH = 2, then paddingH > kernelSizeH * 1/2.
		The input divisorOverride is not within the supported range. However, this check does not apply to Ascend 950PR/Ascend 950DT.

aclnnAvgPool2dBackward

Parameters:

Parameter	Input/Output	Description
workspace	Input	Workspace memory address applied for on the Device side.
workspaceSize	Input	Workspace size applied for on the Device side, obtained from the first-phase API aclnnAvgPool2dBackwardGetWorkspaceSize.
executor	Input	Operator executor, which contains the operator computation flow.
stream	Input	Stream that executes the task.

Return value

aclnnStatus: return code. For details, see aclnn Return Code.

Constraints

Deterministic computation:
- aclnnAvgPool2dBackward defaults to a non-deterministic implementation. You can enable deterministic computation by calling aclrtCtxSetSysParamOpt.
Atlas training products and Atlas inference products: The Cube unit does not support FLOAT32 computation. When the input is FLOAT32, you can set cubeMathType to 1 (ALLOW_FP32_DOWN_PRECISION) to allow the API to internally cast to FLOAT16 for computation.

Example

The following provides example code for reference only. For details about compilation and running, see Compile and Run Samples.

#include <cstdio>
#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_avgpool2d_backward.h"

#define CHECK_RET(cond, return_expr) \
  do {                               \
    if (!(cond)) {                   \
      return_expr;                   \
    }                                \
  } while (0)

#define LOG_PRINT(message, ...)     \
  do {                              \
    printf(message, ##__VA_ARGS__); \
  } while (0)

int64_t GetShapeSize(const std::vector<int64_t>& shape) {
  int64_t shapeSize = 1;
  for (auto i : shape) {
    shapeSize *= i;
  }
  return shapeSize;
}

int Init(int32_t deviceId, aclrtStream* stream) {
  // Boilerplate: resource initialization.
  auto ret = aclInit(nullptr);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclInit failed. ERROR: %d\n", ret); return ret);
  ret = aclrtSetDevice(deviceId);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSetDevice failed. ERROR: %d\n", ret); return ret);
  ret = aclrtCreateStream(stream);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtCreateStream failed. ERROR: %d\n", ret); return ret);
  return 0;
}

template <typename T>
int CreateAclTensor(const std::vector<T>& hostData, const std::vector<int64_t>& shape, void** deviceAddr,
                    aclDataType dataType, aclTensor** tensor, aclFormat Format = aclFormat::ACL_FORMAT_ND) {
  auto size = GetShapeSize(shape) * sizeof(T);
  // Call aclrtMalloc to apply for device memory.
  auto ret = aclrtMalloc(deviceAddr, size, ACL_MEM_MALLOC_HUGE_FIRST);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMalloc failed. ERROR: %d\n", ret); return ret);
  // Call aclrtMemcpy to copy host data to device memory.
  ret = aclrtMemcpy(*deviceAddr, size, hostData.data(), size, ACL_MEMCPY_HOST_TO_DEVICE);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMemcpy failed. ERROR: %d\n", ret); return ret);

  // Calculate the strides of a contiguous tensor.
  std::vector<int64_t> strides(shape.size(), 1);
  for (int64_t i = shape.size() - 2; i >= 0; i--) {
    strides[i] = shape[i + 1] * strides[i + 1];
  }

  // Call aclCreateTensor to create an aclTensor.
  *tensor = aclCreateTensor(shape.data(), shape.size(), dataType, strides.data(), 0, Format, shape.data(), shape.size(), *deviceAddr);
  return 0;
}

int main() {
  // 1. (Boilerplate) Initialize device/stream. See the acl external API list.
  // Enter the deviceId based on the actual device.
  int32_t deviceId = 0;
  aclrtStream stream;
  auto ret = Init(deviceId, &stream);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("Init acl failed. ERROR: %d\n", ret); return ret);

  // 2. Construct the input and output. Customize the construction based on the API.
  std::vector<int64_t> gradOutputShape = {1, 16, 1, 1};
  std::vector<int64_t> selfShape = {1, 16, 4, 4};
  std::vector<int64_t> kernelDims = {4, 4};
  std::vector<int64_t> strideDims = {1, 1};
  std::vector<int64_t> paddingDims = {0, 0};
  bool ceilMode = false;
  int64_t divisorOverride = 0;
  bool countIncludePad = true;
  int8_t cubeMathType = 1;
  std::vector<int64_t> gradInputShape = {1, 16, 4, 4};

  void* gradOutputDeviceAddr = nullptr;
  void* selfDeviceAddr = nullptr;
  void* gradInputDeviceAddr = nullptr;

  aclTensor* gradOutput = nullptr;
  aclTensor* self = nullptr;
  aclTensor* gradInput = nullptr;

  std::vector<float> gradOutputHostData(GetShapeSize(gradOutputShape) * 2, 1);
  std::vector<float> selfHostData(GetShapeSize(selfShape) * 2, 1);
  std::vector<float> gradInputHostData(GetShapeSize(gradInputShape) * 2, 1);

  // Create the gradOutput aclTensor.
  ret = CreateAclTensor(gradOutputHostData, gradOutputShape, &gradOutputDeviceAddr, aclDataType::ACL_FLOAT, &gradOutput, aclFormat::ACL_FORMAT_NCHW);
  CHECK_RET(ret == ACL_SUCCESS, return ret);

  // Create the self aclTensor.
  ret = CreateAclTensor(selfHostData, selfShape, &selfDeviceAddr, aclDataType::ACL_FLOAT, &self, aclFormat::ACL_FORMAT_NCHW);
  CHECK_RET(ret == ACL_SUCCESS, return ret);

  // Create the gradInput aclTensor.
  ret = CreateAclTensor(gradInputHostData, gradInputShape, &gradInputDeviceAddr, aclDataType::ACL_FLOAT, &gradInput, aclFormat::ACL_FORMAT_NCHW);
  CHECK_RET(ret == ACL_SUCCESS, return ret);

  // Create the kernel aclIntArray.
  aclIntArray *kernelSize = aclCreateIntArray(kernelDims.data(), 2);

  // Create the stride aclIntArray.
  aclIntArray *stride = aclCreateIntArray(strideDims.data(), 2);

  // Create the padding aclIntArray.
  aclIntArray *padding = aclCreateIntArray(paddingDims.data(), 2);

  // 3. Call the CANN operator library API. Replace with the actual API name.
  uint64_t workspaceSize = 0;
  aclOpExecutor* executor;
  // Call the first-phase API of aclnnAvgPool2dBackward.
  ret = aclnnAvgPool2dBackwardGetWorkspaceSize(gradOutput,
                                       self,
                                       kernelSize,
                                       stride,
                                       padding,
                                       ceilMode,
                                       countIncludePad,
                                       divisorOverride,
                                       cubeMathType,
                                       gradInput,
                                       &workspaceSize,
                                       &executor);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnAvgPool2dBackwardGetWorkspaceSize failed. ERROR: %d\n", ret); return ret);
  // Apply for device memory based on the workspaceSize calculated by the first-phase API.
  void* workspaceAddr = nullptr;
  if (workspaceSize > 0) {
    ret = aclrtMalloc(&workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("allocate workspace failed. ERROR: %d\n", ret); return ret);
  }
  // Call the second-phase API of aclnnAvgPool2dBackward.
  ret = aclnnAvgPool2dBackward(workspaceAddr, workspaceSize, executor, stream);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnAvgPool2dBackward failed. ERROR: %d\n", ret); return ret);

  // 4. (Boilerplate) Synchronize and wait for task execution to complete.
  ret = aclrtSynchronizeStream(stream);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSynchronizeStream failed. ERROR: %d\n", ret); return ret);

  // 5. Obtain the output value and copy the result from the device memory to the host memory. Modify based on the specific API definition.
  auto size = GetShapeSize(gradInputShape);
  std::vector<float> outData(size, 0);
  ret = aclrtMemcpy(outData.data(), outData.size() * sizeof(outData[0]), gradInputDeviceAddr,
                    size * sizeof(outData[0]), ACL_MEMCPY_DEVICE_TO_HOST);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("copy result from device to host failed. ERROR: %d\n", ret); return ret);
  for (int64_t i = 0; i < size; i++) {
    LOG_PRINT("out result[%ld] is: %f\n", i, outData[i]);
  }

  // 6. Release aclTensor and aclScalar. Modify based on the specific API definition.
  aclDestroyTensor(gradOutput);
  aclDestroyTensor(self);
  aclDestroyTensor(gradInput);
  aclDestroyIntArray(kernelSize);
  aclDestroyIntArray(stride);
  aclDestroyIntArray(padding);

  // 7. Release device resources. Modify based on the specific API definition.
  aclrtFree(gradOutputDeviceAddr);
  aclrtFree(selfDeviceAddr);
  aclrtFree(gradInputDeviceAddr);
  if (workspaceSize > 0) {
    aclrtFree(workspaceAddr);
  }
  aclrtDestroyStream(stream);
  aclrtResetDevice(deviceId);
  aclFinalize();

  return 0;
}