1# tensor.h 2 3<!--Kit: MindSpore Lite Kit--> 4<!--Subsystem: AI--> 5<!--Owner: @zhuguodong8--> 6<!--Designer: @zhuguodong8; @jjfeing--> 7<!--Tester: @principal87--> 8<!--Adviser: @ge-yafang--> 9 10## Overview 11 12Provides tensor-related APIs, which can be used to create tensors and modify tensor information. These APIs are non-thread-safe. 13 14**File to include**: <mindspore/tensor.h> 15 16**Library**: libmindspore_lite_ndk.so 17 18**System capability**: SystemCapability.Ai.MindSpore 19 20**Since**: 9 21 22**Related module**: [MindSpore](capi-mindspore.md) 23 24## Summary 25 26### Structs 27 28| Name| typedef Keyword | Description| 29|----|------------------------------------------------------------|----| 30| void * | [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) | Defines the handle of a tensor object. | 31| void * | [OH_AI_AllocatorHandle](capi-mindspore-oh-ai-allocatorhandle.md) | Defines the handle of the memory allocator. | 32 33### Functions 34 35| Name| Description| 36| -- | -- | 37| [OH_AI_API OH_AI_TensorHandle OH_AI_TensorCreate(const char *name, OH_AI_DataType type, const int64_t *shape,size_t shape_num, const void *data, size_t data_len)](#oh_ai_tensorcreate) | Creates a tensor object.| 38| [OH_AI_API void OH_AI_TensorDestroy(OH_AI_TensorHandle *tensor)](#oh_ai_tensordestroy) | Destroys a tensor object.| 39| [OH_AI_API OH_AI_TensorHandle OH_AI_TensorClone(OH_AI_TensorHandle tensor)](#oh_ai_tensorclone) | Clones a tensor.| 40| [OH_AI_API void OH_AI_TensorSetName(OH_AI_TensorHandle tensor, const char *name)](#oh_ai_tensorsetname) | Sets the tensor name.| 41| [OH_AI_API const char *OH_AI_TensorGetName(const OH_AI_TensorHandle tensor)](#oh_ai_tensorgetname) | Obtains the tensor name.| 42| [OH_AI_API void OH_AI_TensorSetDataType(OH_AI_TensorHandle tensor, OH_AI_DataType type)](#oh_ai_tensorsetdatatype) | Sets the data type of a tensor.| 43| [OH_AI_API OH_AI_DataType OH_AI_TensorGetDataType(const OH_AI_TensorHandle tensor)](#oh_ai_tensorgetdatatype) | Obtains the tensor type.| 44| [OH_AI_API void OH_AI_TensorSetShape(OH_AI_TensorHandle tensor, const int64_t *shape, size_t shape_num)](#oh_ai_tensorsetshape) | Sets the tensor shape.| 45| [OH_AI_API const int64_t *OH_AI_TensorGetShape(const OH_AI_TensorHandle tensor, size_t *shape_num)](#oh_ai_tensorgetshape) | Obtains the tensor shape.| 46| [OH_AI_API void OH_AI_TensorSetFormat(OH_AI_TensorHandle tensor, OH_AI_Format format)](#oh_ai_tensorsetformat) | Sets the tensor data format.| 47| [OH_AI_API OH_AI_Format OH_AI_TensorGetFormat(const OH_AI_TensorHandle tensor)](#oh_ai_tensorgetformat) | Obtains the tensor data format.| 48| [OH_AI_API void OH_AI_TensorSetData(OH_AI_TensorHandle tensor, void *data)](#oh_ai_tensorsetdata) | Sets the tensor data.| 49| [OH_AI_API const void *OH_AI_TensorGetData(const OH_AI_TensorHandle tensor)](#oh_ai_tensorgetdata) | Obtains the pointer to tensor data.| 50| [OH_AI_API void *OH_AI_TensorGetMutableData(const OH_AI_TensorHandle tensor)](#oh_ai_tensorgetmutabledata) | Obtains the pointer to variable tensor data. If the data is empty, memory will be allocated.| 51| [OH_AI_API int64_t OH_AI_TensorGetElementNum(const OH_AI_TensorHandle tensor)](#oh_ai_tensorgetelementnum) | Obtains the number of tensor elements.| 52| [OH_AI_API size_t OH_AI_TensorGetDataSize(const OH_AI_TensorHandle tensor)](#oh_ai_tensorgetdatasize) | Obtains the number of bytes of the tensor data.| 53| [OH_AI_API OH_AI_Status OH_AI_TensorSetUserData(OH_AI_TensorHandle tensor, void *data, size_t data_size)](#oh_ai_tensorsetuserdata) | Sets the tensor as the user data. This function allows you to reuse user data as the model input, which helps to reduce data copy by one time.<br> > **NOTE**<br>The user data is type of external data for the tensor and is not automatically released when the tensor is destroyed. The caller needs to release the data separately. In addition, the caller must ensure that the user data is valid during use of the tensor.| 54| [OH_AI_API OH_AI_AllocatorHandle OH_AI_TensorGetAllocator(OH_AI_TensorHandle tensor)](#oh_ai_tensorgetallocator) | Obtains a memory allocator. The allocator is responsible for allocating memory for tensors.| 55| [OH_AI_API OH_AI_Status OH_AI_TensorSetAllocator(OH_AI_TensorHandle tensor, OH_AI_AllocatorHandle allocator)](#oh_ai_tensorsetallocator) | Sets the memory allocator. The allocator is responsible for allocating memory for tensors.| 56 57## Function Description 58 59### OH_AI_TensorCreate() 60 61``` 62OH_AI_API OH_AI_TensorHandle OH_AI_TensorCreate(const char *name, OH_AI_DataType type, const int64_t *shape,size_t shape_num, const void *data, size_t data_len) 63``` 64 65**Description** 66 67Creates a tensor object. 68 69**Since**: 9 70 71 72**Parameters** 73 74| Name| Description| 75| -- | -- | 76| const char *name | Tensor name.| 77| [OH_AI_DataType](capi-data-type-h.md#oh_ai_datatype) type | Tensor data type.| 78| const int64_t *shape | Tensor dimension array.| 79| size_t shape_num | Length of the tensor dimension array.| 80| const void *data | Data pointer.| 81| size_t data_len | Data length.| 82 83**Returns** 84 85| Type | Description| 86|----------------------------------| -- | 87| OH_AI_API [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) | Handle of the tensor object.| 88 89### OH_AI_TensorDestroy() 90 91``` 92OH_AI_API void OH_AI_TensorDestroy(OH_AI_TensorHandle *tensor) 93``` 94 95**Description** 96 97Destroys a tensor object. 98 99**Since**: 9 100 101 102**Parameters** 103 104| Name| Description| 105| -- | -- | 106| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) *tensor | Level-2 pointer to the tensor handle.| 107 108### OH_AI_TensorClone() 109 110``` 111OH_AI_API OH_AI_TensorHandle OH_AI_TensorClone(OH_AI_TensorHandle tensor) 112``` 113 114**Description** 115 116Clones a tensor. 117 118**Since**: 9 119 120 121**Parameters** 122 123| Name| Description| 124| -- | -- | 125| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | Pointer to the tensor to clone.| 126 127**Returns** 128 129| Type| Description| 130| -- | -- | 131| OH_AI_API [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) | Handle of the new tensor object.| 132 133### OH_AI_TensorSetName() 134 135``` 136OH_AI_API void OH_AI_TensorSetName(OH_AI_TensorHandle tensor, const char *name) 137``` 138 139**Description** 140 141Sets the tensor name. 142 143**Since**: 9 144 145 146**Parameters** 147 148| Name| Description| 149| -- | -- | 150| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | Handle of the tensor object.| 151| const char *name | Tensor name.| 152 153### OH_AI_TensorGetName() 154 155``` 156OH_AI_API const char *OH_AI_TensorGetName(const OH_AI_TensorHandle tensor) 157``` 158 159**Description** 160 161Obtains the tensor name. 162 163**Since**: 9 164 165 166**Parameters** 167 168| Name| Description| 169| -- | -- | 170| const [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | Handle of the tensor object.| 171 172**Returns** 173 174| Type| Description| 175| -- | -- | 176| OH_AI_API const char * | Tensor name.| 177 178### OH_AI_TensorSetDataType() 179 180``` 181OH_AI_API void OH_AI_TensorSetDataType(OH_AI_TensorHandle tensor, OH_AI_DataType type) 182``` 183 184**Description** 185 186Sets the data type of a tensor. 187 188**Since**: 9 189 190 191**Parameters** 192 193| Name| Description| 194| -- | -- | 195| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | Handle of the tensor object.| 196| [OH_AI_DataType](capi-data-type-h.md#oh_ai_datatype) type | Data type. For details, see [OH_AI_DataType](capi-data-type-h.md#oh_ai_datatype).| 197 198### OH_AI_TensorGetDataType() 199 200``` 201OH_AI_API OH_AI_DataType OH_AI_TensorGetDataType(const OH_AI_TensorHandle tensor) 202``` 203 204**Description** 205 206Obtains the tensor type. 207 208**Since**: 9 209 210 211**Parameters** 212 213| Name| Description| 214| -- | -- | 215| const [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | Handle of the tensor object.| 216 217**Returns** 218 219| Type | Description| 220|----------------------------------------------------------------| -- | 221| OH_AI_API [OH_AI_DataType](capi-data-type-h.md#oh_ai_datatype) | Tensor data type.| 222 223### OH_AI_TensorSetShape() 224 225``` 226OH_AI_API void OH_AI_TensorSetShape(OH_AI_TensorHandle tensor, const int64_t *shape, size_t shape_num) 227``` 228 229**Description** 230 231Sets the tensor shape. 232 233**Since**: 9 234 235 236**Parameters** 237 238| Name| Description| 239| -- | -- | 240| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | Handle of the tensor object.| 241| const int64_t *shape | Shape array.| 242| size_t shape_num | Length of the tensor shape array.| 243 244### OH_AI_TensorGetShape() 245 246``` 247OH_AI_API const int64_t *OH_AI_TensorGetShape(const OH_AI_TensorHandle tensor, size_t *shape_num) 248``` 249 250**Description** 251 252Obtains the tensor shape. 253 254**Since**: 9 255 256 257**Parameters** 258 259| Name| Description| 260| -- | -- | 261| const [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | Handle of the tensor object.| 262| size_t *shape_num | Length of the tensor shape array.| 263 264**Returns** 265 266| Type| Description| 267| -- | -- | 268| OH_AI_API const int64_t * | Shape array.| 269 270### OH_AI_TensorSetFormat() 271 272``` 273OH_AI_API void OH_AI_TensorSetFormat(OH_AI_TensorHandle tensor, OH_AI_Format format) 274``` 275 276**Description** 277 278Sets the tensor data format. 279 280**Since**: 9 281 282 283**Parameters** 284 285| Name| Description| 286| -- | -- | 287| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | Handle of the tensor object.| 288| [OH_AI_Format](capi-format-h.md#oh_ai_format) format | Tensor data format.| 289 290### OH_AI_TensorGetFormat() 291 292``` 293OH_AI_API OH_AI_Format OH_AI_TensorGetFormat(const OH_AI_TensorHandle tensor) 294``` 295 296**Description** 297 298Obtains the tensor data format. 299 300**Since**: 9 301 302 303**Parameters** 304 305| Name| Description| 306| -- | -- | 307| const [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | Handle of the tensor object.| 308 309**Returns** 310 311| Type | Description| 312|---------------------------------------------------------| -- | 313| OH_AI_API [OH_AI_Format](capi-format-h.md#oh_ai_format) | Tensor data format.| 314 315### OH_AI_TensorSetData() 316 317``` 318OH_AI_API void OH_AI_TensorSetData(OH_AI_TensorHandle tensor, void *data) 319``` 320 321**Description** 322 323Sets the tensor data. 324 325**Since**: 9 326 327 328**Parameters** 329 330| Name| Description| 331| -- | -- | 332| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | Handle of the tensor object.| 333| void *data | Data pointer.| 334 335### OH_AI_TensorGetData() 336 337``` 338OH_AI_API const void *OH_AI_TensorGetData(const OH_AI_TensorHandle tensor) 339``` 340 341**Description** 342 343Obtains the pointer to tensor data. 344 345**Since**: 9 346 347 348**Parameters** 349 350| Name| Description| 351| -- | -- | 352| const [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | Handle of the tensor object.| 353 354**Returns** 355 356| Type| Description| 357| -- | -- | 358| OH_AI_API const void * | Pointer to tensor data.| 359 360### OH_AI_TensorGetMutableData() 361 362``` 363OH_AI_API void *OH_AI_TensorGetMutableData(const OH_AI_TensorHandle tensor) 364``` 365 366**Description** 367 368Obtains the pointer to variable tensor data. If the data is empty, memory will be allocated. 369 370**Since**: 9 371 372 373**Parameters** 374 375| Name| Description| 376| -- | -- | 377| const [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | Handle of the tensor object.| 378 379**Returns** 380 381| Type| Description| 382| -- | -- | 383| OH_AI_API void * | Pointer to tensor data.| 384 385### OH_AI_TensorGetElementNum() 386 387``` 388OH_AI_API int64_t OH_AI_TensorGetElementNum(const OH_AI_TensorHandle tensor) 389``` 390 391**Description** 392 393Obtains the number of tensor elements. 394 395**Since**: 9 396 397 398**Parameters** 399 400| Name| Description| 401| -- | -- | 402| const [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | Handle of the tensor object.| 403 404**Returns** 405 406| Type| Description| 407| -- | -- | 408| OH_AI_API int64_t | Number of tensor elements.| 409 410### OH_AI_TensorGetDataSize() 411 412``` 413OH_AI_API size_t OH_AI_TensorGetDataSize(const OH_AI_TensorHandle tensor) 414``` 415 416**Description** 417 418Obtains the number of bytes of the tensor data. 419 420**Since**: 9 421 422 423**Parameters** 424 425| Name| Description| 426| -- | -- | 427| const [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | Handle of the tensor object.| 428 429**Returns** 430 431| Type| Description| 432| -- | -- | 433| OH_AI_API size_t | Number of bytes of the tensor data.| 434 435### OH_AI_TensorSetUserData() 436 437``` 438OH_AI_API OH_AI_Status OH_AI_TensorSetUserData(OH_AI_TensorHandle tensor, void *data, size_t data_size) 439``` 440 441**Description** 442 443Sets the tensor as the user data. This function allows you to reuse user data as the model input, which helps to reduce data copy by one time.<br>> **NOTE**<br>The user data is type of external data for the tensor and is not automatically released when the tensor is destroyed. The caller needs to release the data separately. In addition, the caller must ensure that the user data is valid during use of the tensor. 444 445**Since**: 10 446 447 448**Parameters** 449 450| Name| Description| 451| -- | -- | 452| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | Handle of the tensor object.| 453| void *data | Start address of user data.| 454| size_t data_size | Length of the user data length.| 455 456**Returns** 457 458| Type | Description| 459|---------------------------------------------------------| -- | 460| OH_AI_API [OH_AI_Status](capi-status-h.md#oh_ai_status) | Execution status code. The value **OH_AI_STATUS_SUCCESS** indicates that the operation is successful. If the operation fails, an error code is returned.| 461 462### OH_AI_TensorGetAllocator() 463 464``` 465OH_AI_API OH_AI_AllocatorHandle OH_AI_TensorGetAllocator(OH_AI_TensorHandle tensor) 466``` 467 468**Description** 469 470Obtains a memory allocator. The allocator is responsible for allocating memory for tensors. 471 472**Since**: 12 473 474 475**Parameters** 476 477| Name| Description| 478| -- | -- | 479| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | Handle of the tensor object.| 480 481**Returns** 482 483| Type | Description| 484|-------------------------------------| -- | 485| OH_AI_API [OH_AI_AllocatorHandle](capi-mindspore-oh-ai-allocatorhandle.md) | Handle of the memory allocator.| 486 487### OH_AI_TensorSetAllocator() 488 489``` 490OH_AI_API OH_AI_Status OH_AI_TensorSetAllocator(OH_AI_TensorHandle tensor, OH_AI_AllocatorHandle allocator) 491``` 492 493**Description** 494 495Sets the memory allocator. The allocator is responsible for allocating memory for tensors. 496 497**Since**: 12 498 499 500**Parameters** 501 502| Name| Description| 503| -- | -- | 504| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | Handle of the tensor object.| 505| [OH_AI_AllocatorHandle](capi-mindspore-oh-ai-allocatorhandle.md) allocator | Handle of the memory allocator.| 506 507**Returns** 508 509| Type | Description| 510|---------------------------------------------------------| -- | 511| OH_AI_API [OH_AI_Status](capi-status-h.md#oh_ai_status) | Execution status code. The value **OH_AI_STATUS_SUCCESS** indicates that the operation is successful. If the operation fails, an error code is returned.| 512