aclnnCast

Applicable Products

  • Ascend 950PR&950DT products: Supported
  • Atlas A3 products: Supported
  • Atlas A2 products: Supported
  • Atlas 200I/500 A2 inference products: Not supported
  • Atlas inference products: Supported
  • Atlas training products: Supported

Function

Converts the input tensor to the specified dtype.

Function Prototype

Each operator uses a two-phase API. You must first call the "aclnnCastGetWorkspaceSize" API to obtain the workspace size required for computation and the executor that contains the operator computation process, and then call the "aclnnCast" API to execute the computation.

aclnnStatus aclnnCastGetWorkspaceSize(
  const aclTensor   *self,
  const aclDataType  dtype,
  aclTensor         *out,
  uint64_t          *workspaceSize,
  aclOpExecutor    **executor)
aclnnStatus aclnnCast(
  void          *workspace,
  uint64_t       workspaceSize,
  aclOpExecutor *executor,
  aclrtStream    stream)

aclnnCastGetWorkspaceSize

  • Parameters:

    Parameter Input/Output Description Instruction Data Type Data Format Dimension (shape) Non-contiguous Tensor
    self Input Input parameter for the cast computation, which is an aclTensor on the Device side. - FLOAT16, FLOAT, DOUBLE, INT8, UINT8, INT16, UINT16, INT32, UINT32, INT64, UINT64, BOOL, COMPLEX32, COMPLEX64, COMPLEX128, BFLOAT16, HIFLOAT8, FLOAT8_E5M2, FLOAT8_E4M3FN, FLOAT4_E2M1, FLOAT4_E1M2 ND 0-8 √
    dtype Attribute Target dtype to which the input tensor is converted. - const aclDataType - - -
    out Output Output parameter of the cast computation, an aclTensor on the Device side. Same shape as self. FLOAT16, FLOAT, DOUBLE, INT8, UINT8, INT16, UINT16, INT32, UINT32, INT64, UINT64, BOOL, COMPLEX32, COMPLEX64, COMPLEX128, BFLOAT16, HIFLOAT8, FLOAT8_E5M2, FLOAT8_E4M3FN, FLOAT4_E2M1, FLOAT4_E1M2, INT4 (non-contiguous tensors not supported yet) ND 0-8 √
    workspaceSize Output Returns the workspace size to be allocated on the Device side. - - - - -
    executor Output Returns the op executor, which contains the operator computation process. - - - - -
    • Atlas training products and Atlas inference products: BFLOAT16 and INT4 are not supported.
    • Atlas A2 products, Atlas A3 products: COMPLEX32, HIFLOAT8, FLOAT8_E5M2, FLOAT8_E4M3FN, FLOAT4_E2M1, FLOAT4_E1M2, and INT4 are not supported.
  • Return value

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

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

    Error Code Error Code Description
    ACLNN_ERR_PARAM_NULLPTR 161001 tensor or out is a null pointer.
    ACLNN_ERR_PARAM_INVALID 161002 The data type or data format of self is not supported.
    The data format of self is different from that of out.
    The shape of self is different from the shape of out.
    The parameter dtype is not within the range of supported output data formats.
    When the data type of out is INT4, self is a non-contiguous tensor.
    ACLNN_ERR_INNER_TILING_ERROR 561002 When the data type of out is INT4, the last dimension of the shape of self is odd.

aclnnCast

  • Parameters:

    Parameter Input/Output Description
    workspace Input Workspace memory address allocated on the Device side.
    workspaceSize Input Workspace memory size allocated on the Device side, obtained by the first-phase API aclnnCastGetWorkspaceSize.
    executor Input op executor, including the operator computation process.
    stream Input Stream used to execute tasks.
  • Return value

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

Constraints

  • Deterministic computation:

    • aclnnCast defaults to a deterministic implementation.
  • For scenarios where the data type is converted from floating-point to integer: If the input data contains NaN, NaN is converted to 0.

  • For scenarios where the input data type is BOOL, COMPLEX32, COMPLEX64, COMPLEX128, FLOAT4_E2M1, or FLOAT4_E1M2: Non-contiguous input is not supported.

  • Atlas inference products, Atlas training products, Atlas A2 products, Atlas A3 products:
    • For the use case of converting the data type from int32 to int8: Only the input data in the range (-2048, 1920) is guaranteed to be error-free.
    • For the use case of converting the data type from float64/complex64/complex128 to uint8: Only the non-negative input data is guaranteed to be error-free.
  • Atlas inference products:
    • For the use case of converting data type from float32 to int64 and from float32 to uint8, precision is guaranteed only if the input data is within the range (-2147483648, 2147483583).
    • For the use case of converting data type from int64 to float32, precision is guaranteed only if the input data is within the range (-2147483648, 2147483647).
  • Ascend 950PR&950DT products:
    • For scenarios where the output type is INT4: the last axis of the input shape being odd is not supported, and non-contiguous input is not supported.

    • For input and output types involving COMPLEX32, COMPLEX64, FLOAT4_E2M1, FLOAT4_E1M2, HIFLOAT8, FLOAT8_E5M2, FLOAT8_E4M3FN, or INT4, only the conversion paths in the following table are supported:

      self data type out data type
      COMPLEX32 COMPLEX64
      COMPLEX64 COMPLEX32
      COMPLEX32 FLOAT16
      FLOAT16 COMPLEX32
      FLOAT32/BFLOAT16 COMPLEX64
      COMPLEX64 FLOAT32/BFLOAT16
      FLOAT32/FLOAT16/BFLOAT16 FLOAT4_E2M1/FLOAT4_E1M2
      FLOAT4_E2M1/FLOAT4_E1M2 FLOAT32/FLOAT16/BFLOAT16
      FLOAT32/FLOAT16/BFLOAT16 HIFLOAT8/FLOAT8_E5M2/FLOAT8_E4M3FN
      HIFLOAT8/FLOAT8_E5M2/FLOAT8_E4M3FN FLOAT32/FLOAT16/BFLOAT16
      HIFLOAT8/FLOAT8_E5M2/FLOAT8_E4M3FN FLOAT4_E2M1/FLOAT4_E1M2
      FLOAT4_E2M1/FLOAT4_E1M2 HIFLOAT8/FLOAT8_E5M2/FLOAT8_E4M3FN
      INT32 INT4

Example

The sample code is as follows and is for reference only. For details about compilation and execution, see Compile and Run Samples.

#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_cast.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, 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 apply for device-side 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-side data to the device-side 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);

  // 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 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 by referring to the acl API documentation.
  // Set 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> selfShape = {4, 2};
  std::vector<int64_t> outShape = {4, 2};

  void* selfDeviceAddr = nullptr;
  void* outDeviceAddr = nullptr;
  aclTensor* self = nullptr;
  aclTensor* out = nullptr;

  std::vector<float> selfHostData = {0.1, 1.1, 2.1, 3.1, 4.1, 5.1, 6.1, 7.1};
  std::vector<double> outHostData = {0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0};

  // Create the self aclTensor.
  ret = CreateAclTensor(selfHostData, selfShape, &selfDeviceAddr, aclDataType::ACL_FLOAT, &self);
  CHECK_RET(ret == ACL_SUCCESS, return ret);
  // Create the out aclTensor.
  ret = CreateAclTensor(outHostData, outShape, &outDeviceAddr, aclDataType::ACL_DOUBLE, &out);
  CHECK_RET(ret == ACL_SUCCESS, return ret);

  // 3. Call the CANN operator library API. Replace it with the specific API name.
  uint64_t workspaceSize = 0;
  aclOpExecutor* executor;
  // Call the first-phase API aclnnCastGetWorkspaceSize.
  ret = aclnnCastGetWorkspaceSize(self, aclDataType::ACL_DOUBLE, out, &workspaceSize, &executor);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnCastGetWorkspaceSize 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 aclnnCast.
  ret = aclnnCast(workspaceAddr, workspaceSize, executor, stream);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnCast failed. ERROR: %d\n", ret); return ret);

  // 4. (boilerplate) Wait synchronously for the 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, copy the result from device memory to host memory, and modify it based on the specific API definition.
  auto size = GetShapeSize(outShape);
  std::vector<double> 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 modify it based on the specific API definition.
  aclDestroyTensor(self);
  aclDestroyTensor(out);

  // 7. Release device resources.
  aclrtFree(selfDeviceAddr);
  aclrtFree(outDeviceAddr);
  if (workspaceSize > 0) {
    aclrtFree(workspaceAddr);
  }
  aclrtDestroyStream(stream);
  aclrtResetDevice(deviceId);
  aclFinalize();

  return 0;
}