aclCreateTensor

Function Usage

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 execution.

aclTensor is a framework-defined structure used to manage and store tensor data. You can directly use it without paying attention to its internal implementation.

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)

Parameters

• aclDataType is an enumeration class of data types defined by the framework. For details, see "aclDataType".
• aclFormat is an enumeration class of data formats defined by the framework. 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 for 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.

Returns

Created aclTensor on success; else, 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. It 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 is used as an example to describe how to create an x tensor.

  1 2 3 4 5 6 7

  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 is used as an example to describe how to create a transposed x^T tensor corresponding to x:

  1 2 3 4 5 6 7

  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 API execution is as follows. The following code examples are for reference only and are not intended for direct copying and execution:

 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 execution.
auto ret = aclxxXxxGetWorkspaceSize(xTensor, xTransposedTensor, ..., outTensor, ..., &workspaceSize, &executor);
ret = aclxxXxx(...);
...
//Destroy the aclTensor.
ret = aclDestroyTensor(xTensor);
ret = aclDestroyTensor(xTransposedTensor);