aclCreateTensor

Description

Creates an aclTensor object based on the tensor data type, data layout format, dimension, stride, offset, and device storage address. This object is used as the input parameter for single-operator API calls.

aclTensor is a built-in structure for managing and storing tensor data. You can use it without knowing how it works inside.

Prototype

aclTensor *aclCreateTensor(const int64_t *viewDims, uint64_t viewDimsNum, aclDataType dataType, const int64_t *stride, int64_t offset, aclFormat format, const int64_t *storageDims, uint64_t storageDimsNum, void *tensorData)

Parameter Description

• aclDataType is a built-in enumeration class of data types. For details, see aclDataType.
• aclFormat is a built-in enumeration class of data formats. For details, see aclFormat.
• StorageShape and ViewShape of aclTensor:
  • ViewShape indicates the logical shape of the tensor, which is the size of the tensor required in actual use.
  • StorageShape indicates the actual physical layout shape of the tensor, which is the actual size of the tensor in the memory.

  Examples:

  • If StorageShape is [10, 20], the tensor is arranged in the memory based on [10, 20].
  • If ViewShape is [2, 5, 20], the tensor can be considered as a data block [2, 5, 20] for operator use.

Return Value

Created aclTensor on success; otherwise, nullptr.

Constraints

• This API must be used together with aclDestroyTensor. They are used to create and destroy the aclTensor, respectively.
• To create multiple aclTensor objects, call aclCreateTensorList to store the tensor list.
• The DataType of the aclTensor can be obtained by calling aclGetDataType.
• The format of the aclTensor can be obtained by calling aclGetFormat.
• The StorageShape of the aclTensor can be obtained by calling aclGetStorageShape.
• The ViewOffset of the aclTensor, that is, the offset corresponding to the ViewShape, can be obtained by calling aclGetViewOffset.
• The ViewShape of the aclTensor can be obtained by calling aclGetViewShape.
• The ViewStrides of the aclTensor, that is, the stride corresponding to the ViewShape, can be obtained by calling aclGetViewStrides.
• The parameters of a given tensor can be initialized by calling aclInitTensor.
• The following APIs can be called to update or obtain the device memory addresses recorded in the aclTensor in different scenarios.
  • aclSetInputTensorAddr
  • aclSetOutputTensorAddr
  • aclSetTensorAddr
  • aclGetRawTensorAddr
  • aclSetRawTensorAddr

Examples

The definition of aclTensor is similar to that of torch.Tensor. aclTensor consists of a contiguous or discontiguous memory address and a series of description information (such as stride and offset). Based on the shape, stride, and offset information, the tensor can fetch data from the memory and obtain discontiguous memory (for example, y in Figure 1).

Figure 1 Logical structure of a tensor

• Figure 1 shows how to create an x tensor.

  1 2 3 4 5 6

  aclTensor *CreateXTensor() { std::vector<int64_t> viewDims = {2, 4}; std::vector<int64_t> stride = {4, 1}; // The stride of dimension 1 is 4, and the stride of dimension 2 is 1. std::vector<int64_t> storageDims = {2, 4}; return aclCreateTensor(viewDims.data(), 2, ACL_FLOAT16, stride.data(), 0, ACL_FORMAT_ND, storageDims.data(), 2, nullptr); }

• Figure 1 shows how to create a transposed x^T tensor corresponding to x:

  1 2 3 4 5 6

  aclTensor *CreateXTransposedTensor() { std::vector<int64_t> viewDims = {4, 2}; std::vector<int64_t> stride = {1, 4}; // Transpose stride std::vector<int64_t> storageDims = {2, 4}; return aclCreateTensor(viewDims.data(), 2, ACL_FLOAT16, stride.data(), 0, ACL_FORMAT_ND, storageDims.data(), 2, nullptr); }

According to the preceding examples, the code that uses aclTensor as the input parameter for single-operator APIs is as follows. The following code examples are for reference only. Do not copy and run it.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// Create an aclTensor.
aclTensor *xTensor = CreateXTensor();
aclTensor *xTransposedTensor = CreateXTransposedTensor();
// Use the aclTensor as the input parameter for single-operator API calls.
auto ret = aclxxXxxGetWorkspaceSize(xTensor, xTransposedTensor, ..., outTensor, ..., &workspaceSize, &executor);
ret = aclxxXxx(...);
...
// Destroy the aclTensor.
ret = aclDestroyTensor(xTensor);
ret = aclDestroyTensor(xTransposedTensor);