aclnnUniqueDim

Applicable Products

Function

• Operator function: Performs deduplication on the input tensor self along a specified dim axis.

• Example: Assume self is

  $$\begin{bmatrix} \begin{bmatrix} 2 & 1 & 2 \end{bmatrix}\\ \begin{bmatrix} 1 & 2 & 1 \end{bmatrix}\\ \begin{bmatrix} 2 & 1 & 2 \end{bmatrix}\\ \end{bmatrix}$$

  If dim is 0, valueOut is:

  $$\begin{bmatrix} \begin{bmatrix} 2 & 1 & 2 \end{bmatrix}\\ \begin{bmatrix} 1 & 2 & 1 \end{bmatrix}\\ \end{bmatrix}$$

  inverseOut is:

  $$\begin{bmatrix} 0 & 1 & 0 \end{bmatrix}$$

  countsOut is:

  $$\begin{bmatrix} 1 & 2 \end{bmatrix}$$

Function Prototype

Each operator consists of a two-phase API. You must first call the "aclnnUniqueDimGetWorkspaceSize" API to obtain the input parameters and calculate the required workspace size based on the computation process, and then call the "aclnnUniqueDim" API to perform the computation.

aclnnStatus aclnnUniqueDimGetWorkspaceSize(
  const aclTensor* self,
  bool             sorted,
  bool             returnInverse,
  int64_t          dim,
  aclTensor*       valueOut,
  aclTensor*       inverseOut,
  aclTensor*       countsOut,
  uint64_t*        workspaceSize,
  aclOpExecutor**  executor)

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

aclnnUniqueDimGetWorkspaceSize

• Parameters

  Parameter	Input/Output	Description	Instruction	Data Type	Data Format	Shape	Non-contiguous Tensor
  self	Input	self in the example.	-	FLOAT, FLOAT16, UINT8, INT8, UINT16, INT16, UINT32, INT32, UINT64, INT64, DOUBLE, BOOL, BFLOAT16.	ND	1-8	√
  sorted	Input	Indicates whether the returned output valueOut is sorted.	-	-	-	-	-
  returnInverse	Input	Specifies whether to return the position indices of each element of self along the dim axis in the corresponding elements of valueOut. True returns them, and False does not.	-	-	-	-	-
  dim	Input	dim in the example.	Specifies the dimension for the deduplication operation. The data type supports INT64, with a value range of [-self.dim(), self.dim()).	FLOAT, FLOAT16, UINT8, INT8, UINT16, INT16, UINT32, INT32, UINT64, INT64, DOUBLE, BOOL, BFLOAT16	ND		√
  valueOut	Output	valueOut in the example, representing the deduplication result.	The data type is the same as that of self.	-	-	-	-
  inverseOut	Output	inverseOut in the example, indicating the position index of each element of self along the dim axis in the corresponding element of valueOut.	-	INT64	-	-	-
  countsOut	Output	countsOut in the example, indicating the number of occurrences of each element in valueOut within self.	-	INT64	-	-	-
  workspaceSize	Output	Returns the workspace size to be requested on the Device side.	-	-	-	-	-
  executor	Output	Returns the op executor, which contains the operator computation process.	-	-	-	-	-

• Return Value

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

  The first-phase API completes input validation. The following scenarios trigger an error:
  
  <table style="undefined;table-layout: fixed; width: 1035px"><colgroup>
  <col style="width: 262px">
  <col style="width: 103px">
  <col style="width: 670px">
  </colgroup>
  <thead>
    <tr>
      <th>Return Value</th>
      <th>Error Code</th>
      <th>Description</th>
    </tr></thead>
  <tbody>
    <tr>
      <td>ACLNN_ERR_PARAM_NULLPTR</td>
      <td>161001</td>
      <td>The passed self, valueOut, inverseOut, or countsOut is a null pointer.</td>
    </tr>
    <tr>
      <td rowspan="5">ACLNN_ERR_PARAM_INVALID</td>
      <td rowspan="5">161002</td>
      <td>The data type of self is not within the supported range.</td>
    </tr>
    <tr>
      <td>The data types of inverseOut and countsOut are not INT64.</td>
    </tr>
    <tr>
      <td>The data types of self and valueOut are inconsistent.</td>
    </tr>
    <tr>
      <td>The number of dimensions of self's shape is greater than 8.</td>
    </tr>
    <tr>
      <td>The value of dim is not within the range [-self.dim(), self.dim()).</td>
    </tr>
  </tbody>
  </table>

aclnnUniqueDim

• Parameter Description

  Parameter Name	Input/Output	Description
  workspace	Input	The workspace memory address allocated on the Device side.
  workspaceSize	Input	The workspace size allocated on the Device side, obtained by the first-phase API aclnnUniqueDimGetWorkspaceSize.
  executor	Input	The op executor, which contains the operator computation flow.
  stream	Input	Specifies the Stream that executes the task.

• Return Value

  aclnnStatus: Returns the status code. For details, see aclnn Return Code.

Constraints

• Deterministic computation:
  • aclnnUniqueDim uses a deterministic implementation by default.
• Performance:
  • On the A2, A3, and training series products, when the dimension value of self on dim exceeds 200 million, the performance is very poor or even times out.

Example

The sample code is as follows, for reference only. For the specific compilation and execution process, see Compile and Run Samples.

#include <iostream>
#include <vector>
#include "math.h"
#include "acl/acl.h"
#include "aclnnop/aclnn_unique_dim.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) {
  auto size = GetShapeSize(shape) * sizeof(T);
  // Call aclrtMalloc to allocate 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 the aclCreateTensor API to create an aclTensor.
  *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.
  // Set deviceId based on the actual device.
  int32_t deviceId = 0;
  aclrtStream stream;
  auto ret = Init(deviceId, &stream);
  // Handle the check result as needed.
  CHECK_RET(ret == 0, LOG_PRINT("Init acl failed. ERROR: %d\n", ret); return ret);

  // 2. Construct input and output. Customize the construction based on the API.
  std::vector<int64_t> selfShape = {4, 2};
  std::vector<int64_t> valueShape = {3,2};
  std::vector<int64_t> inverseShape = {4, 2};
  std::vector<int64_t> countsShape = {3};
  void* selfDeviceAddr = nullptr;
  void* valueDeviceAddr = nullptr;
  void* inverseDeviceAddr = nullptr;
  void* countsDeviceAddr = nullptr;
  aclTensor* self = nullptr;
  aclTensor* valueOut = nullptr;
  aclTensor* inverseOut = nullptr;
  aclTensor* countsOut = nullptr;
  std::vector<float> selfHostData = {0, 1, 1, 3, 3, 1, 1, 3};
  std::vector<float> valueHostData = {0, 0, 0, 0, 0, 0, 0, 0};
  std::vector<int64_t> inverseHostData = {0, 0, 0, 0, 0, 0, 0, 0};
  std::vector<int64_t> countsHostData = {0, 0, 0, 0, 0, 0, 0, 0};
  bool sorted = false;
  bool returnInverse = false;
  int64_t dim = 0;

  // Create self aclTensor
  ret = CreateAclTensor(selfHostData, selfShape, &selfDeviceAddr, aclDataType::ACL_FLOAT, &self);
  CHECK_RET(ret == ACL_SUCCESS, return ret);
  // Create valueOut aclTensor
  ret = CreateAclTensor(valueHostData, valueShape, &valueDeviceAddr, aclDataType::ACL_FLOAT, &valueOut);
  CHECK_RET(ret == ACL_SUCCESS, return ret);
  // Create inverseOut aclTensor
  ret = CreateAclTensor(inverseHostData, inverseShape, &inverseDeviceAddr, aclDataType::ACL_INT64, &inverseOut);
  CHECK_RET(ret == ACL_SUCCESS, return ret);
  // Create countsOut aclTensor
  ret = CreateAclTensor(countsHostData, countsShape, &countsDeviceAddr, aclDataType::ACL_INT64, &countsOut);
  CHECK_RET(ret == ACL_SUCCESS, return ret);

  // 3. Call the CANN operator library API. Modify based on the specific API.
  uint64_t workspaceSize = 0;
  aclOpExecutor* executor;
  // Call the first-phase API of aclnnUniqueDim.
  ret = aclnnUniqueDimGetWorkspaceSize(self, sorted, returnInverse, dim, valueOut, inverseOut, countsOut, &workspaceSize, &executor);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnUniqueDimGetWorkspaceSize failed. ERROR: %d\n", ret); return ret);
  // Allocate 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 aclnnUniqueDim.
  ret = aclnnUniqueDim(workspaceAddr, workspaceSize, executor, stream);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnUniqueDim 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. Modify based on the specific API definition.
  auto size = GetShapeSize(valueShape);
  std::vector<float> resultData(size, 0);
  ret = aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]), valueDeviceAddr, size * sizeof(float),
                    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 based on the specific API definition.
  aclDestroyTensor(self);
  aclDestroyTensor(valueOut);
  aclDestroyTensor(inverseOut);
  aclDestroyTensor(countsOut);

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

  return 0;
}