aclnnUpsampleBilinear2dBackward

Supported Products

Product	Supported
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

API description: Performs backpropagation of aclnnUpsampleBilinear2d.
Formula:
- Core forward algorithm logic:
  1. Scale the destination image to the same size as the source image.
  2. Calculate points of the scaled destination image and points of adjacent source images.
  3. Calculate the weights from the adjacent points to the target points, and multiply and accumulate the weights to obtain the target point values.
- Calculation logic: An image can be scaled by corner alignment (that is, based on the center point of the pixels in the upper left corner of the source image) or edge alignment (that is, based on the vertex in the upper left corner and two edges of the source image). The two modes differ in the scaling factor and coordinates. Then: $scaleH =\begin{cases} (inputSize[2]-1) / (outputSize[0]-1) & alignCorners=true \\ 1 / scalesH & alignCorners=false\&scalesH>0\\ inputSize[2] / outputSize[0] & alignCorners=false \end{cases}$ $scaleW =\begin{cases} (inputSize[3]-1) / (outputSize[1]-1) & alignCorners=true \\ 1 / scalesW & alignCorners=false\&scalesW>0\\ inputSize[3] / outputSize[1] & alignCorners=false \end{cases}$ Therefore, for a point p (x, y) in a direction of the output, a point mapped back to the source image is denoted as q (x', y'). Then: $x' =\begin{cases} x * scaleH & alignCorners=true \\ MAX(0,{(x+0.5)*scaleH-0.5}) & alignCorners=false \end{cases}$ $y' =\begin{cases} y * scaleW & alignCorners=true \\ MAX(0,{(y+0.5)*scaleW-0.5}) & alignCorners=false \end{cases}$
  - Denoted:
    $x_{0} =int(x'),x_{1} =int(x')+1, lambda_{0} = x_{1}-x', lambda_{1} = 1-lambda_{0}$ $y_{0} =int(y'),y_{1} =int(y')+1, lambdb_{0} = y_{1}-y', lambdb_{1} = 1-lambdb_{0}$
  - Then:
    ${V(p_{x, y})} = {V(p_{x0, y0})} * {lambda_{0}} * {lambdb_{0}} + {V(p_{x0, y1})} * {lambda_{0}} * {lambdb_{1}} + {V(p_{x1, y0})} * {lambda_{1}} * {lambdb_{0}} + {V(p_{x1, y1})} * {lambda_{1}} * {lambdb_{1}}$
  - Assume that the output image out $(x, y)$ for forward interpolation is affected by the original image input $(x_i, y_j)$ . Then:
    $gradInput(x_i,y_j) += gradOutput(x,y) * lambd(x_i,y_j)$

Prototype

Each operator has two-phase API calls. First, aclnnUpsampleBilinear2dBackwardGetWorkspaceSize is called to obtain the workspace size required for computation and the executor that contains the operator computation process. Then, aclnnUpsampleBilinear2dBackward is called to perform computation.

aclnnStatus aclnnUpsampleBilinear2dBackwardGetWorkspaceSize(
  const   aclTensor *gradOut,
  const aclIntArray *outputSize,
  const aclIntArray *inputSize,
  bool               alignCorners,
  double             scalesH,
  double             scalesW,
  aclTensor         *out,
  uint64_t          *workspaceSize,
  aclOpExecutor    **executor)

aclnnStatus aclnnUpsampleBilinear2dBackward(
  void*          workspace,
  uint64_t       workspace_size,
  aclOpExecutor* executor,
  aclrtStream    stream)

aclnnUpsampleBilinear2dBackwardGetWorkspaceSize

Parameters:

Name	Input/Output	Description	Precaution	Data Type	Data Format	Dimension (Shape)	Non-contiguous Tensor
gradOut	Input	Gradient tensor for backpropagation, corresponding to `gradOutput` in the formula.	Empty tensors are not supported.	FLOAT32, FLOAT16, BFLOAT16	NCHW and NHWC	4	√
outputSize	Input	Spatial size of the input `gradOutput` in the H and W dimensions. It corresponds to `outputSize` in the formula.	The size is 2, and each element is greater than 0.	INT64	-	-	-
inputSize	Input	Spatial size of the output `out` in the N, C, H, and W dimensions. It corresponds to `inputSize` in the formula.	The size is 4, and each element is greater than 0.	INT64	-	-	-
alignCorners	Input	Whether to align corner pixels, corresponding to `alignCorners` in the formula.	If True, the input and output tensors are aligned by the center points of their corner pixels, preserving the values at the corner pixels. If False, the input and output tensors are aligned by the corner points of their corner pixels, and the interpolation uses edge value padding for out-of-boundary values so that this operation is independent of the input sizes scalesH and scalesW.	BOOL	-	-	-
scalesH	Input	Multiplier for the output `out` in the height dimension, corresponding to `scalesH` in the formula.	-	DOUBLE	-	-	-
scalesW	Input	Multiplier for the output `out` in the width dimension, corresponding to `scalesW` in the formula.	-	DOUBLE	-	-	-
out	Output	Output tensor for backpropagation, corresponding to `gradInput` in the formula.	Empty tensors are not supported. The data format must be the same as that of `gradOut`.	FLOAT32, FLOAT16, BFLOAT16	NCHW and NHWC	4	√
workspaceSize	Output	Size of the workspace required to be allocated on the device.	-	-	-	-	-
executor	Output	Operator executor, containing the operator computation process.	-	-	-	-	-

Atlas inference products, Atlas training products, Atlas A2 training products/Atlas A2 inference products, and Atlas A3 training products/Atlas A3 inference products:
- The data types of gradOut and out do not support BFLOAT16.
- The data type of out must be the same as that of gradOut.

Returns

aclnnStatus: status code. For details, see aclnn Return Codes.

The first-phase API implements input parameter verification. The following errors may be thrown.

Return	Error Code	Description
ACLNN_ERR_PARAM_NULLPTR	161001	The passed gradOut, outputSize, inputSize, or out is a null pointer.
ACLNN_ERR_PARAM_INVALID	161002	The data type or format of gradOut is not supported.
		The data types of gradOut and out are inconsistent.
		The shape of gradOut is not 4D.
		The size of outputSize is not 2.
		The value of an element of outputSize is less than 1.
		The size of inputSize is not 4.
		The value of an element of inputSize is less than 1.
		The sizes of gradOut and inputSize in the N and C dimensions are inconsistent.
		The sizes of gradOut in the H and W dimensions are inconsistent with those of outputSize[0] and outputSize[1].
		The dimension sizes of the N or C axes of gradOut and out are different.
		The data format of gradOut or out is not supported.

aclnnUpsampleBilinear2dBackward

Parameters:

Name	Input/Output	Description
workspace	Input	Address of the workspace to be allocated on the device.
workspaceSize	Input	Size of the workspace to be allocated on the device, which is obtained by calling the first-phase API aclnnUpsampleBilinear2dBackwardGetWorkspaceSize.
executor	Input	Operator executor, containing the operator computation process.
stream	Input	Stream for executing the task.

Returns:

aclnnStatus: status code. For details, see aclnn Return Codes.

Constraints

Deterministic computing:
- aclnnUpsampleBilinear2dBackward defaults to a deterministic implementation.

Example

The following example is for reference only. For details, see Compilation and Running Sample.

#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_upsample_bilinear_2d_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) {
  // (Fixed writing) Initialize resources.
  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) {
  auto size = GetShapeSize(shape) * sizeof(T);
  // Call aclrtMalloc to allocate memory on the device.
  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 the data on the host to the memory on the device.
  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);

  // Compute the strides of the 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, aclFormat::ACL_FORMAT_NCHW,
                            shape.data(), shape.size(), *deviceAddr);
  return 0;
}

int main() {
  // 1. (Fixed writing) Initialize the device and stream. For details, see the ACL API manual.
  // Set the device ID in use.
  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 based on the API.
  std::vector<int64_t> selfShape = {1, 1, 6, 6};
  std::vector<int64_t> outShape = {1, 1, 3, 3};
  void* selfDeviceAddr = nullptr;
  void* outDeviceAddr = nullptr;
  aclTensor* self = nullptr;
  aclTensor* out = nullptr;
  std::vector<float> selfHostData = {1, 2, 3, 4.1};
  std::vector<float> outHostData = {0, 0, 0, 0, 0, 0, 0, 0, 0};

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

  // Create an out aclTensor.
  ret = CreateAclTensor(outHostData, outShape, &outDeviceAddr, aclDataType::ACL_FLOAT, &out);
  CHECK_RET(ret == ACL_SUCCESS, return ret);

  std::vector<int64_t> outArraySize = {6, 6};
  const aclIntArray *outputSize = aclCreateIntArray(outArraySize.data(), outArraySize.size());
  CHECK_RET(outputSize != nullptr, return ACL_ERROR_INTERNAL_ERROR);

  std::vector<int64_t> inputArraySize = {1, 1, 3, 3};
  const aclIntArray *inputSize = aclCreateIntArray(inputArraySize.data(), inputArraySize.size());
  CHECK_RET(inputSize != nullptr, return ACL_ERROR_INTERNAL_ERROR);

  // 3. Call the CANN operator library API, which needs to be replaced with the actual API.
  uint64_t workspaceSize = 0;
  aclOpExecutor* executor;
  //Call the first-phase API of aclnnUpsampleBilinear2dBackward.
  ret = aclnnUpsampleBilinear2dBackwardGetWorkspaceSize(self, outputSize, inputSize, 1, 2, 2, out, &workspaceSize, &executor);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnUpsampleBilinear2dBackwardGetWorkspaceSize failed. ERROR: %d\n", ret); return ret);
  // Allocate device memory based on the computed workspaceSize.
  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 aclnnUpsampleBilinear2dBackward.
  ret = aclnnUpsampleBilinear2dBackward(workspaceAddr, workspaceSize, executor, stream);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnUpsampleBilinear2dBackward failed. ERROR: %d\n", ret); return ret);

  // 4. (Fixed writing) Wait until the task execution is 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 to the host. Modify the code based on the API definition.
  auto size = GetShapeSize(outShape);
  std::vector<float> resultData(size, 0);
  ret = aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]), outDeviceAddr,
                    size * sizeof(resultData[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("result[%ld] is: %f\n", i, resultData[i]);
  }

  // 6. Release aclTensor and aclScalar. Modify the configuration based on the API definition.
  aclDestroyTensor(self);
  aclDestroyTensor(out);
  aclDestroyIntArray(outputSize);
  aclDestroyIntArray(inputSize);

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