aclCreateTensor

函数功能

创建aclTensor，作为CANN算子API接口的入参。

aclTensor由AscendCL框架定义，用来管理和存储张量数据，开发者无需关注其内部实现。

函数原型

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)

参数说明

aclDataType、aclFormat定义由AscendCL提供，具体参见《应用开发接口》中aclDataType、aclFormat。
关于aclTensor的StorageShape和ViewShape：
- ViewShape表示aclTensor的逻辑shape，是Tensor在实际使用时需要用到的大小。
- StorageShape表示aclTensor的实际物理排布shape，是Tensor在内存上实际存在的大小。
举例如下：
- StorageShape为[10, 20]：表示该aclTensor在内存上是按照[10, 20]排布的。
- ViewShape为[2, 5, 20]：在算子使用时，表示该aclTensor可被视为一块[2, 5, 20]的数据使用。

参数名	输入/输出	说明
viewDims	输入	tensor的ViewShape维度值，取值不支持负数。
viewDimsNum	输入	tensor的ViewShape维度数。
dataType	输入	tensor的数据类型。
stride	输入	tensor的各个维度取下一个值的步长，取值不支持负数。
offset	输入	tensor首元素相对于storage的偏移，取值不支持负数。
format	输入	tensor的数据排布格式。
storageDims	输入	tensor的StorageShape维度值，取值不支持负数。
storageDimsNum	输入	tensor的StorageShape维度数。
tensorData	输入	tensor在Device侧的存储地址。

返回值说明

成功则返回创建好的aclTensor，否则返回nullptr。

约束与限制

本接口与aclDestroyTensor接口配套使用，分别完成aclTensor的创建与销毁。
与aclTensor相关的接口如下：
- 调用aclGetDataType接口可以获取aclTensor的DataType。
- 调用aclGetFormat接口可以获取aclTensor的format。
- 调用aclGetStorageShape接口可以获取aclTensor的StorageShape。
- 调用aclGetViewOffset接口可以获取aclTensor的ViewOffset，即ViewShape对应的offset。
- 调用aclGetViewShape接口可以获取aclTensor的ViewShape。
- 调用aclGetViewStrides接口可以获取aclTensor的ViewStrides，即ViewShape对应的stride。
- 调用aclInitTensor接口初始化给定tensor的参数。
- 调用如下接口可刷新输入/输出aclTensor中记录的Device内存地址。

调用示例

aclTensor的定义与torch.Tensor相似，由一块连续或非连续的内存地址和一系列描述信息（如stride、offset等）组成。Tensor根据shape、stride、offset信息，可自由取出内存中的数据，也可获得非连续的内存（如图1中y）。

图1 tensor逻辑结构

以图1为例，x tensor创建过程如下：↵

aclTensor *CteateXTensor()↵
{↵
    int64_t viewDims = {2, 4};       ↵
    int64_t stride = {4, 1};          // 第1维步长4，第2维步长1↵
    int64_t storageDims = {2, 4};    ↵
    return aclCreateTensor(viewDims, 2, ACL_FLOAT16, stride, 0, ACL_FORMAT_ND, storageDims, 2, nullptr);↵
}↵

以图1为例，x对应的转置x^T tensor创建过程如下：↵

aclTensor *CreateXTransposedTensor()↵
{↵
    int64_t viewDims = {4, 2};       ↵
    int64_t stride = {1, 4};         // 转置跨度通过stride表示↵
    int64_t storageDims = {2, 4};    ↵
    return aclCreateTensor(viewDims, 2, ACL_FLOAT16, stride, 0, ACL_FORMAT_ND, storageDims, 2, nullptr);↵
}↵

aclTensor作为单算子API执行接口的入参示例如下，不可以直接拷贝运行，仅供参考。

// 创建aclTensor
aclTensor *xTensor = CteateXTensor();
aclTensor *xTransposedTensor = CreateXTransposedTensor();
// aclTensor作为单算子API执行接口的入参
auto ret = aclnnXxxGetWorkspaceSize(xTensor, xTransposedTensor, ..., outTensor, ..., &workspaceSize, &executor);
ret = aclnnXxx(...);
...
// 销毁aclTensor
ret = aclDestroyTensor(xTensor);
ret = aclDestroyTensor(xTransposedTensor);

父主题： 基础接口