aclnnConfusionTranspose

Applicable Products

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

Function

Description:

Fuses reshape and transpose operations.
Formula:
1. When transposeFirst is False:
  $y=transpose(reshape(x,shape),perm)$
2. When transposeFirst is True:
  $y=reshape(transpose(x,perm),shape)$

Function Prototype

Each operator is divided into a two-phase API. You must first call the "aclnnConfusionTransposeGetWorkspaceSize" API to obtain the input parameters and calculate the required workspace size based on the computation process, and then call the "aclnnConfusionTranspose" API to perform the computation.

aclnnStatus aclnnConfusionTransposeGetWorkspaceSize(
    const aclTensor    *x,
    const aclIntArray  *perm,
    const aclIntArray  *shape,
    bool                transposeFirst,
    aclTensor          *out,
    uint64_t           *workspaceSize,
    aclOpExecutor      **executor)

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

aclnnConfusionTransposeGetWorkspaceSize

Parameters:

Parameter	Input/Output	Description	Instruction	Data Type	Data Format	Dimension (shape)	Non-contiguous Tensor
x (aclTensor*)	Input/Output	Input tensor, which corresponds to x in the formula.	Supports empty tensors.	INT8, INT16, INT32, INT64, UINT8, UINT16, UINT32, UINT64, FLOAT16, FLOAT, BFLOAT16	ND	1-8	-
perm (aclIntArray*)	Input	The pre-transpose axis index corresponding to each post-transpose axis, i.e., perm in the corresponding formula.	1. The elements in this input must be unique and within the range [0, number of perm dimensions – 1]. 2. When transposeFirst is True, the length of perm must be the same as the length of the shape of x, i.e., len(perm) = len(x_shape). 3. When transposeFirst is False, the length of perm must be the same as the length of the attribute input shape, i.e., len(perm) = len(shape).	INT64	-	-	-
shape (aclIntArray*)	Input	Shape size after reshape, corresponding to shape in the formula.	The product of all dimensions in shape must equal the total number of elements in the input tensor x.	INT64	-	-	-
transposeFirst (bool)	Input	Determines whether to perform the transpose operation first.	If the value is True, transpose is performed first; otherwise, reshape is performed first.	BOOL	-	-	-
out (aclTensor*)	Output	Represents the computation result after reshape and transpose.	-	Consistent with the input x.	Consistent with the input x.	-	-
workspaceSize(uint64_t*)	Output	Returns the workspace size to be requested on the Device side.	-	-	-	-	-
executor(aclOpExecutor**)	Output	Returns the operator executor, which contains the operator computation process.	-	-	-	-	-

Return Value:

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

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

Return Value	Return Code	Description
ACLNN_ERR_PARAM_NULLPTR	161001	The passed x or out is a null pointer.
ACLNN_ERR_PARAM_INVALID	161002	The data types of the input x and out are not within the supported range.
ACLNN_ERR_INNER_NULLPTR	561103	Internal API validation error, usually because the specifications of the input data or attributes are not within the supported range, or the shapes of the input and output do not meet the requirements in the parameter description.

aclnnConfusionTranspose

Parameters:

Parameter	Input/Output	Description
workspace	Input	Address of the workspace memory applied for on the Device side.
workspaceSize	Input	Size of the workspace applied for on the Device side, obtained by the first-phase API aclnnConfusionTransposeGetWorkspaceSize.
executor	Input	Operator executor, which contains the operator computation process.
stream	Input	Specifies the stream for task execution.

return value:

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

Constraints

Deterministic computation description: aclnnConfusionTranspose defaults to a deterministic implementation.

For example:

Let shape_before be the data shape before the reshape operation, and shape_after be the data shape after the reshape operation.

    shape_before = [(ab),(cd),f,(gh)]
    shape_after = [a,(bc),d,e,(fg),h]

The following shape_after is not allowed:

    shape_after_illegal = [a,b,d,e,(fg),(ch)]

Example

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

#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_confusion_transpose.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;
}

void PrintOutResult(std::vector<int64_t> &shape, void** deviceAddr) {
  auto size = GetShapeSize(shape);
  std::vector<float> resultData(size, 0);
  auto ret = aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]),
                         *deviceAddr, 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);
  for (int64_t i = 0; i < size; i++) {
    LOG_PRINT("mean result[%ld] is: %f\n", i, resultData[i]);
  }
}

int Init(int32_t deviceId, aclrtStream* stream) {
  // Boilerplate. 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);
  // Apply for device memory by calling aclrtMalloc.
  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);
  // Copy host data to device memory by calling aclrtMemcpy.
  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 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];
  }

  // Create an aclTensor by calling the aclCreateTensor API.
  *tensor = aclCreateTensor(shape.data(), shape.size(), dataType, strides.data(), 0, aclFormat::ACL_FORMAT_ND,
                            shape.data(), shape.size(), *deviceAddr);
  return 0;
}

int main() {
  // 1. (Boilerplate) Initialize device/stream. See the acl API manual.
  // Fill in the deviceId based on your 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. Custom construction is required based on the API interface.

  // Create the input aclTensor.
  aclTensor* x = nullptr;
  std::vector<int64_t> xShape = {2, 4};
  std::vector<float> xHostData = {1, 2, 3, 4, 5, 6, 7, 8};
  void* xDeviceAddr = nullptr;
  ret = CreateAclTensor(xHostData, xShape, &xDeviceAddr, aclDataType::ACL_FLOAT, &x);
  CHECK_RET(ret == ACL_SUCCESS, return ret);

  // Create perm.
  aclIntArray* perm = nullptr;
  std::vector<int64_t> permData = {1, 0};
  perm = aclCreateIntArray(permData.data(), permData.size());
  CHECK_RET(perm != nullptr, return ret);

  // Create shape.
  aclIntArray* shape = nullptr;
  std::vector<int64_t> shapeData = {2, 4};
  shape = aclCreateIntArray(shapeData.data(), shapeData.size());
  CHECK_RET(shape != nullptr, return ret);

  // Create transposeFirst.
  bool transposeFirst = true;

  // Create the output aclTensor.
  std::vector<int64_t> outShape = {2, 4};
  std::vector<float> outHostData(8, 1);
  aclTensor* out = nullptr;
  void* outDeviceAddr = nullptr;
  // Create the out aclTensor.
  ret = CreateAclTensor(outHostData, outShape, &outDeviceAddr, aclDataType::ACL_FLOAT, &out);
  CHECK_RET(ret == ACL_SUCCESS, return ret);

  // 3. Call the CANN operator library API. Replace with the specific API name.
  uint64_t workspaceSize = 16 * 1024 * 1024;
  aclOpExecutor* executor;

  // Call the first-phase API of aclnnConfusionTranspose.
  ret = aclnnConfusionTransposeGetWorkspaceSize(x, perm, shape, transposeFirst, out, &workspaceSize, &executor);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnConfusionTransposeGetWorkspaceSize 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 aclnnConfusionTranspose.
  ret = aclnnConfusionTranspose(workspaceAddr, workspaceSize, executor, stream);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnConfusionTranspose failed. ERROR: %d\n", ret); return ret);

  // 4. (boilerplate) Synchronously 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 side. Modify based on the specific API definition.
  PrintOutResult(outShape, &outDeviceAddr);

  // 6. Release aclTensor and aclTensor. Modify based on the specific API definition.
  aclDestroyTensor(x);
  aclDestroyTensor(out);

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

  return 0;
}