Skip to content

N
NiuTrans.Tensor
Commit 85792ace by 许诺
Options

update manual

parent a0aa3d49
正在显示 包含 646 行增加 和 581 行删除
doc/manual.md
......@@ -104,14 +104,14 @@ $$
```
#include "XTensor.h" // 引用XTensor定义的头文件
using namepsace nts; // 使用XTensor所在的命名空间nt
using namepsace nts; // 使用XTensor所在的命名空间nts
int main(int argc, const char ** argv)
{
// 声明一个变量tensor，它的类型是XTensor
// 声明一个张量tensor，它的类型是XTensor
XTensor tensor;
// 初始化这个变量为50列*100行的矩阵(2阶张量)
// 初始化这个维度为50列*100行的张量(2阶张量，数据类型为X_FLOAT)
InitTensor2D(&tensor, 50, 100, X_FLOAT);
// 之后可以使用张量tensor了
......@@ -126,23 +126,23 @@ int main(int argc, const char ** argv)
g++ sample.cpp -I~/NiuTrans.Tensor/source/tensor -o sample
```
在sample.cpp中使用了XTensor，它是NiuTrans.Tensor里的一个类，这个类定义了张量所需的数据结构。我们可以使用这个类完成对张量的计算、拷贝等各种操作。XTensor类型的变量被声明后，这个变量需要被初始化，或者说被真正指定为一个张量，比如，指定张量各个维度的大小、张量中每个单元的数据类型、给张量分配内存空间等。InitTensor2D()就是一个张量初始化函数，它把张量初始化为一个矩阵，有四个参数：指向被初始化的张量的指针，矩阵的列数，矩阵的行数，数据单元的类型。这里X_FLOAT，是NiuTrans.Tensor自定义的枚举类型，它表示单精度浮点数。我们也可以使用X_INT或者X_DOUBLE，将数据类型指定为32bit整数或者双精度浮点数。
在sample.cpp中使用了XTensor，它是NiuTrans.Tensor里的一个类，这个类定义了张量所需的数据结构，我们可以使用这个类轻松完成对张量的计算、拷贝等各种操作。XTensor类型的变量被声明后，还需要被初始化，或者说被真正指定为一个张量，比如，需要指定张量的各个维度、张量中每个单元的数据类型、给张量分配内存空间等。InitTensor2D()就是一个张量初始化函数，它把张量初始化为一个矩阵，有四个参数：指向被初始化的张量的指针，矩阵的列数，矩阵的行数，数据单元的类型。这里X_FLOAT，是NiuTrans.Tensor自定义的枚举类型，它表示单精度浮点数，我们也可以使用X_INT或X_DOUBLE，将数据类型指定为32bit整数或者双精度浮点数。
NiuTrans.Tensor也提供了其它方式定义张量。比如可以直接调用一个函数完成张量的创建，而且可以显性释放张量。下面是一段示例代码（sample2.cpp）：
```
#include "XTensor.h" // 引用XTensor定义的头文件
using namepsace nts; // 使用XTensor所在的命名空间nt
using namepsace nts; // 使用XTensor所在的命名空间nts
int main(int argc, const char ** argv)
{
// 构建一个单精度浮点类型张量，它是一个50列*100行的矩阵
// 构建一个单精度浮点类型张量，张量维度为50列*100行
XTensor * tensor = NewTensor2D(50, 100, X_FLOAT);
// 之后可以使用张量tensor了
// 之后就可以使用张量tensor了
// 释放这个张量
// 最后需要释放这个张量
DelTensor(tensor);
return 0;
......@@ -153,29 +153,29 @@ sample2.cpp銝凋蝙ewTensor2DelTensor銝蝏嚗
> 注意，在NiuTrans.Tensor中所有张量默认都是“稠密”张量，也就是张量中所有的单元都会被分配空间，而且这些空间是连续的。有些情况下，张量里的单元仅有少数为非零单元，对于这类张量，可以使用“稀疏"的表示方法，这样可以有效的节省存储空间。
如果要定义稀疏张量，需要在原有的参数基础上额外指定一个参数 - 稠密度。所谓稠密度是指非零单元的比例，他是介于0和1之间的一个实数，0表示所有单元全为零，1表示全为非零单元。默认所有张量的稠密度都是1。下面是不同类型张量的定义方法示例（sample3.cpp）
如果要定义稀疏张量，需要在原有的参数基础上额外指定一个参数 - 稠密度。所谓稠密度是指非零单元的比例，他是介于0和1之间的一个实数，0表示所有单元为零，1表示所有单元为非零。默认所有张量的稠密度都是1。下面是不同类型张量的定义方法示例（sample3.cpp）
```
#include "XTensor.h" // 引用XTensor定义的头文件
using namepsace nts; // 使用XTensor所在的命名空间nt
using namepsace nts; // 使用XTensor所在的命名空间nts
int main(int argc, const char ** argv)
{
// 构建一个单精度浮点类型张量，它是一个50列*100行的矩阵
// 构建一个单精度浮点类型张量，维度为50列*100行
// 这个张量是稠密的
XTensor * tensor0 = NewTensor2D(50, 100, X_FLOAT);
// 构建一个单精度浮点类型张量，它是一个50列*100行的矩阵
// 构建一个单精度浮点类型张量，维度为50列*100行
// 这个张量是稠密的
XTensor * tensor1 = NewTensor2D(50, 100, X_FLOAT, 1.0F);
// 构建一个单精度浮点类型张量，它是一个50列*100行的矩阵
// 构建一个单精度浮点类型张量，维度为50列*100行
// 这个张量是稀疏的，有10%的单元非零
XTensor * tensor2 = NewTensor2D(50, 100, X_FLOAT, 0.1F);
// 之后可以使用张量tensor0，tensor1和tensor2了
// 之后就可以使用张量tensor0，tensor1和tensor2了
// 释放这些张量
DelTensor(tensor0);
......@@ -190,12 +190,10 @@ int main(int argc, const char ** argv)
| 功能 | 函数| 参数 |
| - | - | - |
| 初始化张量 | void InitTensor(<br>XTensor * tensor, const int myOrder, <br> const int * myDimSize, <br> const TENSOR_DATA_TYPE myDataType = X_FLOAT, <br> const float myDenseRatio, <br>const int myDevID = -1, XMem * myMem = NULL) <br> <br> <br> | tensor - 指向被初始化张量的指针 <br> myOrder - 张量的维度 <br> myDimSize - 张量每一维的大小，索引0表示第一维 <br> myDenseRatio - 张量的稠密度，1表示稠密张量 <br> myDataType - 张量的数据类型 <br> myDevID - 张量所在的设备ID <br> myMem - 张量所使用的内存池 |
| 初始化稠密张量 | void InitTensor(<br>XTensor * tensor, const int myOrder, <br> const int * myDimSize, <br> const TENSOR_DATA_TYPE myDataType = X_FLOAT, <br>const int myDevID = -1, XMem * myMem = NULL) <br> <br> | tensor - 指向被初始化张量的指针 <br> myOrder - 张量的维度 <br> myDimSize - 张量每一维的大小，索引0表示第一维 <br> myDataType - 张量的数据类型 <br> myDevID - 张量所在的设备ID <br> myMem - 张量所使用的内存池 |
| 初始化张量 | void InitTensor(<br>XTensor * tensor, const int myOrder, <br> const int * myDimSize, <br> const TENSOR_DATA_TYPE myDataType = X_FLOAT, <br> const float myDenseRatio = 1.0F, <br>const int myDevID = -1, XMem * myMem = NULL) <br> <br> <br> | tensor - 指向被初始化张量的指针 <br> myOrder - 张量的维度 <br> myDimSize - 张量每一维的大小，索引0表示第一维 <br> myDenseRatio - 张量的稠密度，1表示稠密张量 <br> myDataType - 张量的数据类型 <br> myDevID - 张量所在的设备ID <br> myMem - 张量所使用的内存池 |
| 创建空张量 | XTensor * NewTensor() | N/A |
| 创建张量 | XTensor * NewTensor(<br>const int myOrder, <br> const int * myDimSize, const float myDenseRatio, <br> const TENSOR_DATA_TYPE myDataType = X_FLOAT, <br>const int myDevID = -1, XMem * myMem = NULL) <br> <br> | myOrder - 张量的维度 <br> myDimSize - 张量每一维的大小，索引0表示第一维 <br> myDenseRatio - 张量的稠密度，1表示稠密张量 <br> myDataType - 张量的数据类型 <br> myDevID - 张量所在的设备ID <br> myMem - 张量所使用的内存池 |
| 创建稠密张量 | XTensor * NewTensor(<br>const int myOrder, <br> const int * myDimSize, <br> const TENSOR_DATA_TYPE myDataType = X_FLOAT, <br>const int myDevID = -1, XMem * myMem = NULL) <br> | myOrder - 张量的维度 <br> myDimSize - 张量每一维的大小，索引0表示第一维 <br> myDataType - 张量的数据类型 <br> myDevID - 张量所在的设备ID <br> myMem - 张量所使用的内存池 |
| 销毁张量 | void DelTensor(const XTensor * tensor) | tensor - 指向要被销毁的张量的指针 |
| 创建张量 | XTensor * NewTensor(<br>const int myOrder, const int * myDimSize, <br> const TENSOR_DATA_TYPE myDataType = X_FLOAT, <br> const float myDenseRatio = 1.0F, <br>const int myDevID = -1, XMem * myMem = NULL) <br> <br> | myOrder - 张量的维度 <br> myDimSize - 张量每一维的大小，索引0表示第一维 <br> myDenseRatio - 张量的稠密度，1表示稠密张量 <br> myDataType - 张量的数据类型 <br> myDevID - 张量所在的设备ID <br> myMem - 张量所使用的内存池 |
| 销毁张量 | void DelTensor(XTensor * tensor) | tensor - 指向要被销毁的张量的指针 |
上述函数中需要说明的是
......@@ -211,20 +209,7 @@ int main(int argc, const char ** argv)
| X_INT8 | 8bit整数（计划支持）|
| X_FLOAT16 | 16bit浮点数（计划支持） |
此外，NiuTrans.Tensor也提供了更多种类的张量初始化和创建方法：
| 功能 | 函数 | 参数 |
| - | - | - |
| 初始化为稠密向量 | void InitTensor1D(<br>XTensor * tensor, const int num, <br> const TENSOR_DATA_TYPE myDataType = X_FLOAT, <br>const int myDevID = -1, XMem * myMem = NULL) <br> <br> | tensor - 指向被初始化张量的指针 <br> num - 向量维度大小 <br> myDataType - 张量的数据类型 <br> myDevID - 张量所在的设备ID <br> myMem - 张量所使用的内存池 |
| 初始化为稠密矩阵 | void InitTensor2D(<br>XTensor * tensor, const int colNum, const int rowNum, <br> const TENSOR_DATA_TYPE myDataType = X_FLOAT, <br>const int myDevID = -1, XMem * myMem = NULL) <br> <br> <br> | tensor - 指向被初始化张量的指针 <br> colNum - 矩阵列数 <br> rowNum - 矩阵行数 <br> myDataType - 张量的数据类型 <br> myDevID - 张量所在的设备ID <br> myMem - 张量所使用的内存池 |
| 初始化为3维稠密张量 | void InitTensor3D(<br>XTensor * tensor, <br> const int d0, const int d1, const int d2, <br> const TENSOR_DATA_TYPE myDataType = X_FLOAT, <br>const int myDevID = -1, XMem * myMem = NULL) <br> <br> <br> | tensor - 指向被初始化张量的指针 <br> d0 - 张量第一维大小 <br> d1 - 张量第二维大小 <br> d2 - 张量第三维大小 <br> myDataType - 张量的数据类型 <br> myDevID - 张量所在的设备ID <br> myMem - 张量所使用的内存池 |
| 初始化为4维稠密张量 | void InitTensor4D(<br>XTensor * tensor, <br> const int d0, const int d1, const int d2, const int d3, <br> const TENSOR_DATA_TYPE myDataType = X_FLOAT, <br>const int myDevID = -1, XMem * myMem = NULL) <br> <br> <br> <br> | tensor - 指向被初始化张量的指针 <br> d0 - 张量第一维大小 <br> d1 - 张量第二维大小 <br> d2 - 张量第三维大小 <br> d3 - 张量第四维大小 <br> myDataType - 张量的数据类型 <br> myDevID - 张量所在的设备ID <br> myMem - 张量所使用的内存池 |
| 初始化为5维稠密张量 | void InitTensor5D(<br>XTensor * tensor, <br> const int d0, const int d1, const int d2, <br> const int d3, const int d4, <br> const TENSOR_DATA_TYPE myDataType = X_FLOAT, <br>const int myDevID = -1, XMem * myMem = NULL) <br> <br> <br> <br> | tensor - 指向被初始化张量的指针 <br> d0 - 张量第一维大小 <br> d1 - 张量第二维大小 <br> d2 - 张量第三维大小 <br> d3 - 张量第四维大小 <br> d4 - 张量第五维大小 <br> myDataType - 张量的数据类型 <br> myDevID - 张量所在的设备ID <br> myMem - 张量所使用的内存池 |
| 创建稠密向量 | XTensor * NewTensor1D(<br>const int num, <br> const TENSOR_DATA_TYPE myDataType = X_FLOAT, <br>const int myDevID = -1, XMem * myMem = NULL) <br> | num - 向量维度大小 <br> myDataType - 张量的数据类型 <br> myDevID - 张量所在的设备ID <br> myMem - 张量所使用的内存池 |
| 创建稠密矩阵 | XTensor * NewTensor2D(<br>const int colNum, const int rowNum, <br> const TENSOR_DATA_TYPE myDataType = X_FLOAT, <br>const int myDevID = -1, XMem * myMem = NULL) <br> <br> | colNum - 矩阵列数 <br> rowNum - 矩阵行数 <br> myDataType - 张量的数据类型 <br> myDevID - 张量所在的设备ID <br> myMem - 张量所使用的内存池 |
| 创建3维稠密张量 | XTensor * NewTensor3D(<br> const int d0, const int d1, const int d2, <br> const TENSOR_DATA_TYPE myDataType = X_FLOAT, <br>const int myDevID = -1, XMem * myMem = NULL) <br> <br> <br> | d0 - 张量第一维大小 <br> d1 - 张量第二维大小 <br> d2 - 张量第三维大小 <br> myDataType - 张量的数据类型 <br> myDevID - 张量所在的设备ID <br> myMem - 张量所使用的内存池 |
| 创建4维稠密张量 | XTensor * NewTensor4D(<br>const int d0, const int d1, const int d2, const int d3, <br> const TENSOR_DATA_TYPE myDataType = X_FLOAT, <br>const int myDevID = -1, XMem * myMem = NULL) <br> <br> <br> <br> | d0 - 张量第一维大小 <br> d1 - 张量第二维大小 <br> d2 - 张量第三维大小 <br> d3 - 张量第四维大小 <br> myDataType - 张量的数据类型 <br> myDevID - 张量所在的设备ID <br> myMem - 张量所使用的内存池 |
| 创建5维稠密张量 | XTensor * NewTensor5D(<br>const int d0, const int d1, const int d2, <br> const int d3, const int d4, <br> const TENSOR_DATA_TYPE myDataType = X_FLOAT, <br>const int myDevID = -1, XMem * myMem = NULL) <br> <br> <br> <br> | d0 - 张量第一维大小 <br> d1 - 张量第二维大小 <br> d2 - 张量第三维大小 <br> d3 - 张量第四维大小 <br> d4 - 张量第五维大小 <br> myDataType - 张量的数据类型 <br> myDevID - 张量所在的设备ID <br> myMem - 张量所使用的内存池 |
此外，NiuTrans.Tensor也提供了更多种类的张量初始化和创建方法，详见~/NiuTrans.Tensor/source/tensor/XTensor.h。
## 访问张量中的内容
......@@ -252,12 +237,12 @@ int main(int argc, const char ** argv)
| 设置张量每一维度的大小 | void SetDim(int * myDimSize) |myDimSize - 张量每一维度的大小 |
| 得到张量中给定的维度大小 | int GetDim(const int dim) | dim - 张量的维度 |
| 重新调整矩阵维度 | void Reshape(<br> const int order, const int * myDimSize) | order - 张量的维度 <br> myDimSize - 张量每一维的大小 |
| 得到张量中元素数量 | int GetSize() | N/A |
| 得到张量中元素数量 | int GetSize() const | N/A |
| 用数组赋值张量 | void SetData(<br> const void * d, int num, int beg = 0) | d - 赋值数组 <br> num - 数组大小 <br> beg - 赋值时从张量的第几位开始 |
| 张量中所有元素设置为0 | void SetZeroAll(XStream * stream = NULL) | stream - 多线程流|
| 获取二维张量的值 | DTYPE Get2D(int ni, int mi = 0) | ni - 行值 <br> mi - 列值 |
| 设置二维张量中<br> 的单元值 | bool Set2D(DTYPE value, int ni, int mi = 0) | value - 单元值 <br> ni - 行值 <br> mi - 列值 |
| 增加二维张量中<br> 的单元值 | bool Add2D(DTYPE value, int ni, int mi = 0) | value - 单元值 <br> ni - 行值 <br> mi - 列值 |
| 获取二维张量的值 | DTYPE Get2D(int ni, int mi) const | ni - 行值 <br> mi - 列值 |
| 设置二维张量中<br> 的单元值 | bool Set2D(DTYPE value, int ni, int mi) | value - 单元值 <br> ni - 行值 <br> mi - 列值 |
| 增加二维张量中<br> 的单元值 | bool Add2D(DTYPE value, int ni, int mi) | value - 单元值 <br> ni - 行值 <br> mi - 列值 |
| 将矩阵重置为特定大小 | bool Resize(<br> const int myOrder, <br> const int * myDimSize, <br> const TENSOR_DATA_TYPE myDataType = DEFAULT_DTYPE, <br> const float myDenseRatio = 1.0F) | myOrder - 张量的维度 <br> myDimSize - 张量每一维的大小,索引0表示第一维 <br> myDataType - 张量的数据类型 <br> myDenseRatio - 张量的稠密度，1表示稠密张量 |
| 将矩阵重置为<br> 另一矩阵大小 | bool Resize(<br> const XTensor * myTensor) | myTensor - 重置矩阵大小的参考矩阵 |
| 依据给定张量<br>释放数据空间 | void DelTensor(<br>const XTensor * tensor) | tensor - 给定张量 |
......@@ -272,11 +257,12 @@ NiuTrans.Tensor鈭恣蝞嚗蜓閬銝鈭
### 代数计算(arithmetic)
此部分主要包括各种数学运算，加、减、乘、除、取负等。
此部分主要包括多种数学运算，如张量加法、减法、乘法、除法等。
#### 除法（Div）
##### 什么是张量的除法？
利用张量的除法运算可以将两个张量相除并得到一个新的张量，两个维度分别为\\(2 \times 2\\)的张量相除过程如下所示：
$$
......@@ -287,39 +273,108 @@ $$
##### 张量除法的调用
NiuTrans.Tensor提供了张量的除法操作，在NiuTrans.Tensor/Tensor/core/arithmetic中定义
NiuTrans.Tensor提供了张量的除法操作，函数接口在NiuTrans.Tensor/source/tensor/core/arithmetic/Div.h中定义，计算方式为:
$$
c(i) = \frac{a(i)}{b(i)} + \alpha * c(i)
$$
张量除法的调用方式以及参数说明如下所示:
```
void _Div(const XTensor * a, const XTensor * b, XTensor * c, DTYPE alpha = 0.0, int leadingDim = 0)
void _DivMe(XTensor * a, const XTensor * b, DTYPE alpha = 0.0, int leadingDim = 0)
```C++
void Div(const XTensor &a, const XTensor &b, XTensor &c, DTYPE alpha = 0.0, int leadingDim = 0);
void DivMe(const XTensor &a, const XTensor &b, DTYPE alpha = 0.0, int leadingDim = 0);
XTensor Div(const XTensor &a, const XTensor &b, DTYPE alpha = 0.0, int leadingDim = 0)
XTensor Div(const XTensor &a, const XTensor &b, DTYPE alpha = 0.0, int leadingDim = 0)；
```
Parameters:
* a - 输入张量
* b - 输人张量
* c - 输出张量
* alpha - 系数
* leadingDim - 沿着某一维度执行广播操作
Parameters:
* a(XTensor) - 输入张量
* b(XTensor) - 输入张量
* c(XTensor, optional) - 输出张量
* alpha(DTYPE) - 系数，默认为0
* leadingDim(int) - 广播维度，沿某一维度执行广播操作，默认为0
##### 张量除法片段示例
用Div进行张量除法操作的示例代码为：
张量除法的示例代码为：
```C++
XTensor a, b, c;
a.Rand(2, 2);
b.Rand(2, 2);
c = a + b;
a.Dump(stdout, "a");
b.Dump(stdout, "b");
c.Dump(stdout, "c");
```
输出结果为：
> a order=2 dimsize=2,2 dtype=X_FLOAT dense=1.000000
2.469558e-01 5.701468e-01 3.389996e-01 1.876888e-01
b order=2 dimsize=2,2 dtype=X_FLOAT dense=1.000000
5.639210e-01 3.753777e-03 4.722739e-01 7.217323e-01
c order=2 dimsize=2,2 dtype=X_FLOAT dense=1.000000
8.108768e-01 5.739006e-01 8.112736e-01 9.094211e-01
张量除法的测试文件路径为：
NiuTrans.Tensor/source/tensor/test/TDiv.cpp
#### 张量屏蔽（Mask）
##### 什么是张量屏蔽？
利用张量屏蔽，可以根据mask张量将输入张量对应位置的值设置为指定值。如果mask张量某个位置的值为0，则输出张量对应位置设置为$\alpha$（默认为0），否则设置为输入张量对应位置的值。
##### 张量屏蔽的调用
NiuTrans.Tensor提供了张量的屏蔽操作，函数接口在NiuTrans.Tensor/source/tensor/core/arithmetic/Mask.h中定义。计算方式为：
$$
\begin{cases}
a(i) = a(i) & if \ mask\ (i) \ is \ non-zero \\
a(i) = \alpha & if \ mask(i) = 0
\end{cases}
$$
张量屏蔽的调用方式以及参数说明如下所示:
```C++
void Mask(const XTensor &a, const XTensor &mask, XTensor &c, DTYPE alpha = 0.0)；
void MaskMe(XTensor &a, const XTensor &mask, DTYPE alpha = 0.0)；
XTensor Mask(const XTensor &a, const XTensor &mask, DTYPE alpha = 0.0)；
```
/* call Div function */
t = Div(*s1, *s2, 0);
Parameters:
* a(XTensor) - 输入张量
* mask(XTensor) - 屏蔽张量
* c(XTensor, optional) - 输出张量
* alpha(DTYPE) - 系数，默认为0
##### 张量屏蔽片段示例
张量屏蔽的示例代码为：
```C++
```
有关张量取绝对值的详细代码示例：
NiuTrans.Tensor/Tensor/test/TDiv.cpp
张量屏蔽的测试文件路径为：
#### 矩阵乘法（MatrixMul）
##### 什么是张量间矩阵乘法？
利用矩阵乘法可以将矩阵想乘并得到一个新的结果矩阵，两个维度分别为\\(2 \times 3\\)和\\(3 \times 2\\)的矩阵相乘过程如下所示，结果矩阵的维度为\\(2 \times 2\\)：
##### 什么是张量的矩阵乘法？
利用矩阵乘法可以将矩阵相乘并得到一个新的结果矩阵，两个维度分别为\\(2 \times 3\\)和\\(3 \times 2\\)的矩阵相乘过程如下所示，结果矩阵的维度为\\(2 \times 2\\)：
$$
\left(\begin{matrix}1.0 & 2.0 & 3.0\\\\-4.0 & 5.0 & 6.0\end{matrix}\right) ×
......@@ -329,36 +384,140 @@ $$
##### 矩阵乘法的调用
NiuTrans.Tensor提供了矩阵乘法的计算操作，在NiuTrans.Tensor/Tensor/core/arithmetic中定义，函数定义为：
>c\_{i,j} = trans(ai) * trans(bj) * alpha + c_{i,j} * beta
NiuTrans.Tensor提供了矩阵乘法的计算操作，在NiuTrans.Tensor/Tensor/core/arithmetic/MatrixMul.h中定义，函数定义为：
$$
c_{i,j} = trans(a_i) * trans(b_j) * \alpha + c_{i,j} * \beta
$$
矩阵乘法的调用方式以及参数说明如下所示:
```
void _MatrixMul(XTensor * a, MATRIX_TRANS_TYPE transposedA, XTensor * b, MATRIX_TRANS_TYPE transposedB, XTensor * c, DTYPE alpha = (DTYPE)1.0, DTYPE beta = 0)
XTensor MatrixMul(const XTensor &a, MATRIX_TRANS_TYPE transposedA, const XTensor &b, MATRIX_TRANS_TYPE transposedB, DTYPE alpha = (DTYPE)1.0, DTYPE beta = 0)
```C++
void MatrixMul(const XTensor &a, MATRIX_TRANS_TYPE transposedA, const XTensor &b, MATRIX_TRANS_TYPE transposedB, XTensor &c,DTYPE alpha = (DTYPE)1.0, DTYPE beta = 0, XPRunner * parallelRunner = NULL);
XTensor MatrixMul(const XTensor &a, MATRIX_TRANS_TYPE transposedA, const XTensor &b, MATRIX_TRANS_TYPE transposedB, DTYPE alpha = (DTYPE)1.0, XPRunner * parallelRunner = NULL);
void MatrixMul(const XTensor &a, MATRIX_TRANS_TYPE transposedA, const XTensor &b, MATRIX_TRANS_TYPE transposedB,XTensor &c, DTYPE alpha = (DTYPE)1.0, XPRunner * parallelRunner = NULL);
XTensor MatrixMul(const XTensor &a, const XTensor &b, DTYPE alpha = (DTYPE)1.0, XPRunner * parallelRunner = NULL);
void MatrixMul(const XTensor &a, const XTensor &b, XTensor &c, DTYPE alpha = (DTYPE)1.0, XPRunner * parallelRunner = NULL);
```
Parameters:
* a - 输入张量1
* transposedA - a是否进行转置
* b - 输入张量2
* transposedB - b是否进行转置
* c - 输出张量
* alpha - 系数α
* beta - 系数β
Parameters:
* a(XTensor) - 输入张量1
* transposedA(MATRIX_TRANS_TYPE) - a是否进行转置
* b(XTensor) - 输入张量2
* transposedB(MATRIX_TRANS_TYPE) - b是否进行转置
* c(XTensor, optional) - 输出张量
* alpha(DTYPE) - 系数，默认为1.0
* beta(DTYPE) - 系数，默认为1.0
* parallelRunner(XPRunner) - 并行处理模块
##### 矩阵乘法片段示例
我们以最基本的二维矩阵乘法为例，用MatrixMul进行矩阵乘法操作的示例代码为：
```
以最基本的二维矩阵乘法为例，矩阵乘法的示例代码为：
```C++
/* call MatrixMul function */
t = MatrixMul(*s1, X_NOTRANS, *s2, X_NOTRANS);
```
有关矩阵乘法的详细代码示例：
矩阵乘法的的测试文件路径为：
NiuTrans.Tensor/Tensor/test/TMatrixMul.cpp
#### 矩阵Batch乘法（MatrixMulBatched）
##### 什么是张量间矩阵Batch乘法？
利用矩阵Batch乘法可以将矩阵相乘并得到一个新的结果矩阵，两个维度分别为\\(2 \times 2 \times 3\\)和\\(2 \times 3 \times 2\\)的矩阵相乘过程如下所示，结果矩阵的维度为\\(2 \times 2 \times 2\\)：
$$
\left(\left(\begin{matrix}0.0 & -1.0 & 2.0\\\\2.0 & 1.0 & 3.0\end{matrix}\right),\left(\begin{matrix}1.0 & 2.0 & 4.0\\\\3.0 & 1.0 & 2.0\end{matrix}\right)\right) ×
\left(\left(\begin{matrix}1.0 & 2.0\\\\-4.0 & 3.0\\\\2.0 & 6.0\end{matrix}\right), \left(\begin{matrix}1.0 & 2.0\\\\3.0 & 4.0\\\\5.0 & 6.0\end{matrix}\right)\right) \rightarrow
\left(\left(\begin{matrix}8.0 & 9.0\\\\4.0 & 25.0\end{matrix}\right),\left(\begin{matrix}27.0 & 34.0\\\\16.0 & 22.0\end{matrix}\right)\right)
$$
##### 矩阵Batch乘法的调用
NiuTrans.Tensor提供了矩阵Batch乘法的计算操作，在NiuTrans.Tensor/Tensor/core/arithmetic/MatrixMulBatched.h中定义，函数定义为：
$$
c_i = trans(a_i) * trans(b_i) * \alpha + c_m * \beta
$$
矩阵Batch乘法的调用方式以及参数说明如下所示:
```C++
XTensor MatrixMulBatched(const XTensor &a, MATRIX_TRANS_TYPE transposedA, const XTensor &b, MATRIX_TRANS_TYPE transposedB,DTYPE alpha = (DTYPE)1.0, XPRunner * parallelRunner = NULL);
XTensor MatrixMulBatched(const XTensor &a, const XTensor &b, DTYPE alpha = (DTYPE)1.0, XPRunner * parallelRunner = NULL);
```
Parameters:
* a(XTensor) - 输入张量1
* transposedA(MATRIX_TRANS_TYPE) - a是否进行转置
* b(XTensor) - 输入张量2
* transposedB(MATRIX_TRANS_TYPE) - b是否进行转置
* c(XTensor, optional) - 输出张量
* alpha(DTYPE) - 系数，默认为1.0
* beta(DTYPE, optional) - 系数，默认为0
* parallelRunner(XPRunner) - 并行处理模块，默认为NULL
##### 矩阵Batch乘法片段示例
矩阵Batch乘法的示例代码为：
```C++
```
矩阵Batch乘法的的测试文件路径为：
NiuTrans.Tensor/Tensor/test/TMatrixMulBatched.cpp
#### 线性变换（MulAndShift）
##### 什么是张量的线性变换？
利用线性变换可以将对输入张量进行线性变换并对结果进行偏移。
##### 线性变换的调用
NiuTrans.Tensor提供了张量线性变换的计算操作，在NiuTrans.Tensor/Tensor/core/arithmetic/MulAndShift.h中定义，函数定义为：
$$
c = x * w + b
$$
张量线性变换的调用方式以及参数说明如下所示:
```C++
XTensor MulAndShift(const XTensor &x, const XTensor &w, const XTensor &b,DTYPE alpha = (DTYPE)1.0, XPRunner * parallelRunner = NULL);
```
Parameters:
* x(XTensor) - 输入张量
* w(XTensor) - 输入张量
* b(XTensor) - 输入张量
* alpha(DTYPE) - 系数，默认为1.0
* parallelRunner(XPRunner) - 并行处理模块，默认为NULL
##### 线性变换片段示例
线性变换的示例代码为：
```C++
```
线性变换的测试文件路径为：
#### 点乘（Multiply）
##### 什么是张量点乘？
......@@ -371,36 +530,43 @@ $$
\left(\begin{matrix}0.0 & 1.0\\\\4.0 & 9.0\end{matrix}\right)
$$
##### 张量点乘的调用
NiuTrans.Tensor提供了张量点乘的计算操作，用来计算张量中元素点乘结果，该函数在NiuTrans.Tensor/Tensor/core/arithmetic/Multiply.h中定义，计算方式为：
> c\_{i,j} = a\_{i,j} * b\_{i,j} + c\_{i,j} * alpha
$$
c_{i,j} = a_{i,j} * b_{i,j} + c_{i,j} * \alpha
$$
##### 张量点乘的调用
张量点乘的调用方式以及参数说明如下所示：
NiuTrans.Tensor提供了张量点乘的计算操作，用来计算张量中元素点乘结果，该函数在NiuTrans.Tensor/Tensor/core/arithmetic中定义，张量点乘的调用方式以及参数说明如下所示:
```
_Multiply(XTensor * a, XTensor * b, XTensor * c, DTYPE alpha = 0.0, int leadingDim=0)
```C++
void Multiply(const XTensor &a, const XTensor &b, XTensor &c, DTYPE alpha = 0.0, int leadingDim = 0);
void MultiplyMe(XTensor &a, const XTensor &b, DTYPE alpha = 0.0, int leadingDim = 0);
void _MultiplyMe(XTensor * a, const XTensor * b, DTYPE alpha = 0.0, int leadingDim = 0)
XTensor Multiply(const XTensor &a, const XTensor &b, DTYPE alpha = 0.0, int leadingDim = 0);
XTensor Multiply(const XTensor &a, const XTensor &b, DTYPE alpha = 0.0, int leadingDim = 0)
```
Parameters:
* a - 输入张量1
* b - 输入张量2
* c - 输出张量
* leadingDim - 沿着指定维度进行点乘操作
* alpha - 系数
Parameters:
* a(XTensor) - 输入张量
* b(XTensor) - 输入张量
* c(XTensor, optional)- 输出张量
* alpha(DTYPE) - 系数，默认为0.0
* leadingDim(int) - 沿着指定维度进行点乘操作，默认为0
##### 张量点乘片段示例
用Multiply进行s1和s2张量间的点乘操作的调用示例如下所示，计算结果存入t中：
```
张量点乘的示例代码为：
```C++
/* call multiply function */
t = Multiply(*s1, *s2, 0);
```
有关矩阵乘法的详细代码示例见：
张量点乘的测试文件路径为：
NiuTrans.Tensor/Tensor/test/TMultiply.cpp
......@@ -417,33 +583,43 @@ $$
##### 张量取负的调用
NiuTrans.Tensor提供了张量取负的计算操作，进行张量的按元素位置进行取负操作，该函数在NiuTrans.Tensor/Tensor/core/arithmetic中定义，张量取负的调用方式以及参数说明如下所示:
```
void _Negate(const XTensor * a, XTensor * b)
NiuTrans.Tensor提供了张量取负的计算操作，进行张量的按元素位置进行取负操作，该函数在NiuTrans.Tensor/Tensor/core/arithmetic/Negate.h中定义，计算方式为：
$$
b = -a
$$
张量取负的调用方式以及参数说明如下所示:
void _NegateMe(XTensor * a)
```C++
void Negate(const XTensor &a, XTensor &b);
XTensor Negate(const XTensor & a)
void NegateMe(XTensor &a);
XTensor Negate(const XTensor & a);
```
Parameters:
* a - 输入张量
* b - 输出张量
Parameters：
* a(XTensor) - 输入张量
* b(XTensor) - 输出张量
##### 张量取负片段示例
用Negate进行张量取负操作的调用示例如下所示，其中a为我们要进行处理的张量，b为得到的结果张量：
```
张量取负的示例代码为：
```C++
/* call negate function */
b = Negate(*aGPU);
```
有关张量取负的详细代码示例见：
张量取负的测试文件路径为：
NiuTrans.Tensor/Tensor/test/TNegate.cpp
#### 符号函数（Sign）
#### 符号（Sign）
##### 什么是张量的符号函数？
##### 什么是张量的符号操作？
张量的符号函数用来取得张量中每一元素的符号，一个维度为\\(3 \times 2\\)的张量符号函数操作过程如下所示：
......@@ -452,35 +628,40 @@ $$
\left(\begin{matrix}1.0 & -1.0\\\\0.0 & 1.0\\\\1.0 & -1.0\end{matrix}\right)
$$
##### 张量符号函数的调用
##### 张量符号的调用
NiuTrans.Tensor提供了张量的符号函数，该函数在NiuTrans.Tensor/Tensor/core/arithmetic中定义，张量符号函数的调用方式以及参数说明如下所示:
```
void _Sign(const XTensor * a, XTensor * b)
NiuTrans.Tensor提供了张量的符号函数，该函数在NiuTrans.Tensor/Tensor/core/arithmetic/Sign.h中定义，张量符号函数的调用方式以及参数说明如下所示:
void _SignMe(XTensor * a)
```C++
void Sign(const XTensor &a, XTensor &b);
XTensor Sign(const XTensor & a)
void SignMe(XTensor &a);
XTensor Sign(const XTensor &a);
```
Parameters:
* a - 输入张量
* b - 输出张量
Parameters:
##### 张量符号函数片段示例
* a(XTensor) - 输入张量
* b(XTensor) - 输出张量
用Sign进行张量符号函数的调用示例如下所示，其中a为我们要进行处理的张量，b为得到的结果张量：
```
##### 张量符号片段示例
符号函数的示例代码为：
```C++
/* call Sign function */
b = Sign(*a);
```
有关张量符号函数的详细代码示例见：
张量符号的测试文件路径为：
NiuTrans.Tensor/Tensor/test/TSign.cpp
#### 减法（Sub）
##### 什么是张量减法？
张量减法的目的是将两个张量相减得到一个新的结果张量，结果张量某一位置的元素数值为进行操作的张量在该位置上元素的差，在张量减法的计算过程中进行操作的张量与结果张量的维度相同，两个维度为\\(2\times 3\\)的张量减法过程如下所示：
$$
......@@ -491,37 +672,47 @@ $$
##### 张量减法的调用
NiuTrans.Tensor提供了张量减法的计算操作，在NiuTrans.Tensor/Tensor/core/arithmetic中定义，该操作用来进行张量之间的按元素位置相减，并得到相减的结果张量，张量减法的调用方法为：
```
void _Sub(const XTensor * a, const XTensor * b, XTensor * c, DTYPE beta = (DTYPE)1.0)
NiuTrans.Tensor提供了张量减法的计算操作，在NiuTrans.Tensor/Tensor/core/arithmetic/Sub.h中定义，该操作用来进行张量之间的按元素位置相减，并得到相减的结果张量，计算方式为：
$$
c = a - b * \beta
$$
其中，a和b为输入张量，c为输出张量，$\beta$为缩放系数，默认为1.0。
张量减法的调用方式以及参数说明如下所示：
void _SubMe(XTensor * a, const XTensor * b, DTYPE beta = (DTYPE)1.0)
```C++
void Sub(const XTensor &a, const XTensor &b, XTensor &c, DTYPE beta = (DTYPE)1.0);
void SubMe(XTensor &a, const XTensor &b, DTYPE beta = (DTYPE)1.0)
XTensor Sub(const XTensor &a, const XTensor &b, DTYPE beta = (DTYPE)1.0)
```
其中a和b为输入张量，c为结果张量，若c为NULL则将相加结果存入a中，beta为一个缩放参数，缩放公式为：c = a - b * beta，beta默认为1.0，NiuTrans.Tensor中张量减法的调用方式以及参数说明如下所示:
Parameters:
Parameters:
* a - 输入张量1
* b - 输入张量2
* c - 输出张量
* beta - 缩放参数
* a(XTensor) - 输入张量
* b(XTensor) - 输入张量
* c(XTensor, optional) - 输出张量
* beta(DTYPE) - 缩放系数，默认为1.0
##### 张量减法片段示例
调用Sub进行张量间的减法操作如下所示，在此例中将张量相减结果存入c中：
```
张量减法的示例代码为：
```C++
/* call Sub function */
c = Sub(*a, *b);
```
详细代码示例见：
张量减法的测试文件路径为：
NiuTrans.Tensor/Tensor/test/TSub.cpp
#### 加法（Sum）
##### 什么是张量加法？
张量加法的目的是将n个张量相加得到一个新的结果张量，结果张量某一位置的元素数值为进行操作的张量在该位置上元素的求和，在张量加法的计算过程中进行操作的张量与结果张量的维度相同，两个维度为\\(2\times 3\\)的张量相加过程如下所示：
$$
......@@ -532,107 +723,43 @@ $$
##### 张量加法的调用
NiuTrans.Tensor提供了张量加法的计算操作，在NiuTrans.Tensor/Tensor/core/arithmetic中定义，该操作用来进行张量之间的按元素位置相加，并得到相加的结果张量，张量加法的调用方法为：
```
void _Sum(const XTensor * a, const XTensor * b, XTensor * c, DTYPE beta = (DTYPE)1.0)
void _SumMe(XTensor * a, const XTensor * b, DTYPE beta = (DTYPE)1.0)
XTensor Sum(const XTensor &a, const XTensor &b, DTYPE beta = (DTYPE)1.0)
```
其中a和b为输入张量，c为结果张量，若c为NULL则将相加结果存入a中，beta为一个缩放参数，缩放公式为：c = a + b * beta，beta默认为1.0，NiuTrans.Tensor中张量加法的调用方式以及参数说明如下所示:
Parameters:
* a - 输入张量1
* b - 输入张量2
* c - 输出张量
* beta - 缩放参数
##### 张量加法片段示例
调用Sum进行张量间的求和操作如下所示，在此例中将张量相加结果存入c中：
```
/* call sum function */
c = Sum(*a, *b);
```
详细代码示例见：
NiuTrans.Tensor/Tensor/test/TSum.cpp
#### SumByColumnTV
##### 什么是SumByColumnTV？
SumByColumnTV的作用是将一个Tensor和一个Vector按列相加，所得结果维度与Tensor一致，一个\\(2 \times 4\\)的Tensor和一个\\(2 \times 1\\)的Vector的SumByColumnTV操作过程如下所示：
NiuTrans.Tensor提供了张量加法的计算操作，在NiuTrans.Tensor/Tensor/core/arithmetic中定义，该操作用来进行张量之间的按元素位置相加，并得到相加的结果张量，计算方式为：
$$
\left(\begin{matrix}0.0 & 1.0 & 2.0 & 3.0\\\\4.0 & 5.0 & 6.0 & 7.0\end{matrix}\right) + \left(\begin{matrix}1.0\\\\0.0\end{matrix}\right) \rightarrow
\left(\begin{matrix}1.0 & 2.0 & 3.0 & 4.0\\\\4.0 & 5.0 & 6.0 & 7.0\end{matrix}\right)
c = a + b * \beta
$$
##### SumByColumnTV的调用
其中，a和b为输入张量，c为输出张量，$\beta$为缩放系数，$\beta$默认为1.0，
NiuTrans.Tensor提供了张量的SumByColumnTV操作，调用方法及参数说明如下所示:
```
void _SumByColumnTV(XTensor * a, XTensor * b, XTensor * c, DTYPE beta)
```
Parameters:
* a - 输入张量
* b - 输入向量
* c - 输出张量
* beta - 缩放参数
张量加法的调用方式以及参数说明如下所示：
调用SumByColumnTV进行的运算为c_col = a_col + b * \beta
```C++
void Sum(const XTensor &a, const XTensor &b, XTensor &c, DTYPE beta = (DTYPE)1.0);
##### SumByColumnTV片段示例
void SumMe(XTensor &a, const XTensor &b, DTYPE beta = (DTYPE)1.0);
SumByColumnTV示例代码如下，其中a为输入的张量，b为输入的向量，c为a和b按列相加所得结果：
XTensor Sum(const XTensor &a, const XTensor &b, DTYPE beta = (DTYPE)1.0);
```
/* call SumByColumnTV function */
void _SumByColumnTV(a, b, c);
```
有关张量SumByColumnTV的详细代码示例见：
NiuTrans.Tensor/Tensor/test/TSumByColumnTV.cpp
#### SumByColumnVT
##### 什么是SumByColumnVT？
SumByColumnVT的作用是将一个Vector和一个Tensor按列相加，所得结果维度与Vector一致，一个\\(2 \times 1\\)的Vector和一个\\(2 \times 4\\)的Tensor的SumByColumnVT操作过程如下所示：
$$
\left(\begin{matrix}1.0\\\\0.0\end{matrix}\right) + \left(\begin{matrix}0.0 & 1.0 & 2.0 & 3.0\\\\4.0 & 5.0 & 6.0 & 7.0\end{matrix}\right) \rightarrow
\left(\begin{matrix}7.0\\\\22.0\end{matrix}\right)
$$
##### SumByColumnVT调用
NiuTrans.Tensor提供了张量的SumByColumnVT操作，调用方法及参数说明如下所示:
```
_SumByColumnVT(XTensor * a, XTensor * b, XTensor * c, DTYPE beta)
```
Parameters:
* a - 输入向量
* b - 输入张量
* c - 输出向量
* beta - 缩放参数
* a(XTensor) - 输入张量
* b(XTensor) - 输入张量
* c(XTensor, optional) - 输出张量
* beta(DTYPE) - 缩放系数，默认为1.0
调用SumByColumnVT进行的运算为c = a + \sum{col} b_col * \beta
##### 张量加法片段示例
##### SumByColumnVT片段示例
张量加法的示例代码为：
SumByColumnVT示例代码如下，其中a为输入的向量，b为输入的张量，c为a和b按列相加所得结果：
```
/* call SumByColumnVT function */
_SumByColumnVT(a, b, c);
```C++
/* call sum function */
c = Sum(*a, *b);
```
有关张量SumByColumnVT的详细代码示例见：
NiuTrans.Tensor/Tensor/test/TSumByColumnVT.cpp
张量加法的测试文件路径为：
NiuTrans.Tensor/Tensor/test/TSum.cpp
### 张量存取(getandset)
......@@ -1021,52 +1148,33 @@ NiuTrans.Tensor/Tensor/test
##### 什么是张量的CopyIndexed操作？
CopyIndexed，即按指定索引位置拷贝张量，一个\\(2 \times 2 \times 3\\)的张量拷贝过程如下所示，本例中是对张量维度2上起始位置索引为0和2的1个元素进行拷贝，所得张量维度为\\(2 \times 2 \times 2\\)：
CopyIndexed，即按指定索引位置拷贝张量，一个\\(3 \times 2 \times 3\\)的张量拷贝过程如下所示，本例中是对张量维度2上起始位置索引为0和2的1个元素进行拷贝，所得张量维度为\\(2 \times 2 \times 2\\)：
$$
\begin{aligned}
\Biggl(
& \left(
\begin{matrix}0.0 & -1.0 & 2.0\\\\2.0 & 1.0 & 3.0\end{matrix}\right),\\\\
& \left(
\begin{matrix}1.0 & 2.0 & 4.0\\\\3.0 & 1.0 & 2.0\end{matrix}
\right),\\\\
& \left(
\begin{matrix}-1.0 & 3.0 & 2.0\\\\1.0 & -1.0 & 0.0\end{matrix}
\right)
\Biggr)
\end{aligned} \rightarrow
\begin{aligned}
\Biggl(
& \left(
\begin{matrix}0.0 & 2.0\\\\2.0 & 3.0\end{matrix}\right),\\\\
& \left(
\begin{matrix}1.0 & 4.0\\\\3.0 & 2.0\end{matrix}
\right),\\\\
& \left(
\begin{matrix}-1.0 & 2.0\\\\1.0 & 0.0\end{matrix}
\right)
\Biggr)
\end{aligned}
$$
$$\begin{aligned}\Biggl( & \left( \begin{matrix}0.0 & -1.0 & 2.0\\\\2.0 & 1.0 & 3.0\end{matrix}\right), & \left( \begin{matrix}1.0 & 2.0 & 4.0\\\\3.0 & 1.0 & 2.0\end{matrix}\right), & \left( \begin{matrix}-1.0 & 3.0 & 2.0\\\\1.0 & -1.0 & 0.0\end{matrix}\right) \Biggr)\end{aligned}$$
$$\downarrow$$
$$\begin{aligned}\Biggl( & \left(\begin{matrix}0.0 & 2.0\\\\2.0 & 3.0\end{matrix}\right), & \left( \begin{matrix}1.0 & 4.0\\\\3.0 & 2.0\end{matrix}\right),& \left( \begin{matrix}-1.0 & 2.0\\\\1.0 & 0.0\end{matrix}\right) \Biggr)\end{aligned}$$
##### 张量CopyIndexed的调用
NiuTrans.Tensor提供了张量的CopyIndexed操作，调用方法及参数说明如下所示:
```
void _CopyIndexed(const XTensor * s, XTensor * t, int dim, int * srcIndex, int indexSize, int * tgtIndex, int copyNum)
```C++
void CopyIndexed(const XTensor &s, XTensor &t, int dim, int &srcIndex, int indexSize, int &tgtIndex,int copyNum = 1);
XTensor CopyIndexed(const XTensor &s, int dim, int * srcIndex,int indexSize, int * tgtIndex, int copyNum)
void CopyIndexed(const XTensor &s, XTensor &t, int dim, const XTensor &srcIndex, const XTensor &tgtIndex, int copyNum = 1);
XTensor CopyIndexed(const XTensor & s, int dim, const XTensor & srcIndex, const XTensor & tgtIndex,int copyNum = 1);
```
Parameters:
* s - 输入张量
* t - 输出张量
* dim - 在哪一维对张量进行CopyIndexed操作
* srcIndex - 源索引，即在指定dim上进行赋值的值的索引
* indexSize - 源索引的个数
* tgtIndex - 目标索引，所赋值的值在输出张量中的索引
* copyNum - 以源索引为起始位置拷贝的元素个数
* s(XTensor) - 输入张量
* t(XTensor, optional) - 输出张量
* dim(int) - 在哪一维对张量进行CopyIndexed操作
* srcIndex(int) - 源索引，即在指定dim上进行赋值的值的索引
* indexSize(int，optional) - 源索引的个数
* tgtIndex(XTensor) - 目标索引，所赋值的值在输出张量中的索引
* copyNum(int) - 以源索引为起始位置拷贝的元素个数，默认为1
##### 张量CopyIndexed片段示例
......@@ -1094,18 +1202,21 @@ $$
##### 张量拷贝操作的调用
NiuTrans.Tensor提供了张量的拷贝操作，调用方法及参数说明如下所示:
```
void _CopyValues(const XTensor * s, XTensor * t, XStream * stream = NULL)
```C++
void CopyValues(const XTensor &s, XTensor &t, XStream &stream = NULL);
void _CopyValues(const XTensor * s, const int sBeg, const int sLen, XTensor * t, const int tBeg, XStream * stream = NULL)
void CopyValues(const XTensor &s, const int sBeg, const int sLen, XTensor &t, const int tBeg, XStream &stream = NULL);
XTensor CopyValues(const XTensor &s, XStream * stream = NULL)
XTensor CopyValues(const XTensor &s, XStream * stream = NULL);
```
Parameters:
* s - 输入张量
* t - 输出张量
* stream - 多线程流
* s(XTensor) - 输入张量
* t(XTensor，optional) - 输出张量
* stream(XStream) - 多线程流，默认为NULL
* sBeg(int，optional) - 源端片段起始
* sLen(int，optional) - 片段长度
* tBeg(int，optional) - 目标端片段起始
##### 张量拷贝片段示例
......@@ -1118,40 +1229,11 @@ t = CopyValues(*s);
NiuTrans.Tensor/Tensor/test/TCopyValues.cpp
#### 采集（gather）
##### 什么是张量的采集操作？
#### gather
张量的采集操作，即将张量中元素按给定索引取出。
#### Spread
##### 张量采集操作的调用
NiuTrans.Tensor提供了张量的采集操作，调用方法及参数说明如下所示:
```
void _Gather(const XTensor * s, XTensor * t, int dim, int * srcIndex, int indexSize)
XTensor Gather(const XTensor &s, int dim, int * srcIndex, int indexSize)
XTensor Gather(const XTensor &s, const XTensor &index)
```
Parameters:
* s - 输入张量
* t - 输出张量
* dim - 沿指定维度进行操作
* srcIndex - 给定索引
* indexSize - 给定索引大小
##### 张量采集片段示例
张量采集示例代码如下，其中s为输入的待操作张量：
```
/* call Gather function */
t = Gather(*s, dim, srcIndex, indexSize);
```
有关张量采集的详细代码示例见：
NiuTrans.Tensor/Tensor/test/TGather.cpp
### 规约操作(reduce)
......@@ -1174,16 +1256,16 @@ $$
##### 张量归约取最大值操作的调用
NiuTrans.Tensor提供了张量的ReduceMax操作，用来获得张量中沿指定维度取得的最大值，张量归约取最大值操作的调用方式及参数说明如下所示:
```
void _ReduceMax(const XTensor * input, XTensor * output, int dim)
```C++
void ReduceMax(const XTensor &input, XTensor &output, int dim);
XTensor ReduceMax(const XTensor &input, int dim)
```
Parameters:
* input - 输入张量
* output - 输出张量
* dim - 沿着指定维度进行取最大值操作
* input(XTensor) - 输入张量
* output(XTensor，optional) - 输出张量
* dim(int) - 沿着指定维度进行取最大值操作
##### 张量归约取最大值片段示例
......@@ -1216,18 +1298,18 @@ $$
##### 张量归约取均值操作的调用
NiuTrans.Tensor提供了张量的ReduceMean操作，调用方法为：
```
void _ReduceMean(const XTensor * input, XTensor * output, int dim)
```C++
void ReduceMean(const XTensor &input, XTensor &output, int dim);
XTensor ReduceMean(const XTensor &input, int dim)
XTensor ReduceMean(const XTensor &input, int dim);
```
ReduceMean用来获得张量中沿指定维度取得的数值均值，张量归约取均值的参数说明如下所示:
Parameters:
* input - 输入张量
* output - 输出张量
* dim - 沿着指定维度进行取平均值操作
* input(XTensor) - 输入张量
* output(XTensor，optional) - 输出张量
* dim(int) - 沿着指定维度进行取平均值操作
##### 张量归约取均值片段示例
......@@ -1261,21 +1343,27 @@ $$
##### 张量归约求和操作的调用
NiuTrans.Tensor提供了张量的ReduceSum操作，调用方法为：
```
void _ReduceSum(const XTensor * input, XTensor * output, int dim, const XTensor * shift = NULL, DTYPE power = (DTYPE)1.0F, bool isExp = false)
XTensor ReduceSum(const XTensor &input, int dim, const XTensor &shift = NULLTensor, DTYPE power = (DTYPE)1.0F, bool isExp = false)
```C++
void ReduceSum(const XTensor &input, XTensor &output, int dim, const XTensor &shift, DTYPE power = (DTYPE)1.0F, bool isExp = false);
void ReduceSum(const XTensor &input, XTensor &output, int dim, DTYPE power = (DTYPE)1.0F, bool isExp = false);
XTensor ReduceSum(const XTensor &input, int dim, const XTensor &shift, DTYPE power = (DTYPE)1.0F, bool isExp = false);
XTensor ReduceSum(const XTensor &input, int dim, DTYPE power = (DTYPE)1.0F, bool isExp = false);
```
其中shift默认为NULL，power默认为1.0F，isExp默认为false，张量归约求和操作的参数说明如下所示:
Parameters:
* input - 输入张量
* output - 输出张量
* dim - 沿着指定维度进行取最大值操作
* shift - 输入的偏移，默认为NULL
* power - 元素的幂，默认为1.0F
* isExp - 是否取指，默认为false
* input(XTensor) - 输入张量
* output(XTensor，optional) - 输出张量
* dim(int) - 沿着指定维度进行取最大值操作
* shift(XTensor，optional) - 输入的偏移
* power(XTensor) - 元素的幂，默认为1.0F
* isExp(bool) - 是否取指，默认为false
##### 张量归约求和片段示例
......@@ -1289,81 +1377,115 @@ t2 = ReduceSum(*s, 1, *shift2);
NiuTrans.Tensor/Tensor/test/TReduceSum.cpp
#### 归约取方差（ReduceSumSquared）
#### 归约求总和（ReduceSumAll）
##### 什么是张量的归约取方差操作？
##### 什么是张量的归约求总和操作？
张量的归约取方差操作是沿着张量的某一维度，计算该张量在该维度的方差,一个\\(2 \times 4\\)的张量在维度0进行取方差操作的过程如下所示：
张量的归约求总和操作是沿着张量的某一维度，计算该张量的总和,一个\\(2 \times 4\\)的张量在维度0进行取方差操作的过程如下所示：
$$
\left(\begin{matrix}0.0 & 1.0 & 2.0 & 3.0\\\\4.0 & 5.0 & 6.0 & 7.0\end{matrix}\right) \rightarrow
\left(\begin{matrix}8.0 & 8.0 & 8.0 & 8.0\end{matrix}\right)
28
$$
##### 张量归约取方差操作的调用
##### 张量归约求总和操作的调用
NiuTrans.Tensor提供了张量的ReduceSumSquared操作，调用方法为：
NiuTrans.Tensor提供了张量的ReduceSumAll操作，调用方法为：
```C++
DTYPE ReduceSumAll(const XTensor & source);
```
void _ReduceSumSquared(const XTensor * input, XTensor * output, int dim, const XTensor * shift)
ReduceSumAll用来计算张量的总和，张量归约取方差操作的参数说明如下所示:
Parameters:
XTensor ReduceSumSquared(const XTensor &input, int dim, const XTensor &shift)
* source(XTensor) - 输入张量
##### 张量归约求总和片段示例
调用ReduceSumAll进行张量归约求总和操作的示例代码如下所示：
```
/* call reduce sum squared function */
t = ReduceSumSquared(*s, 0, *shift);
```
有关张量归约求总和的详细代码示例见：
NiuTrans.Tensor/Tensor/test/TReduceSumAll.cpp
#### 归约取平方和（ReduceSumSquared）
##### 什么是张量的归约取平方和操作？
张量的归约取平方和操作是沿着张量的某一维度，计算该张量在该维度的平方和,一个\\(2 \times 4\\)的张量在维度0进行取方差操作的过程如下所示：
$$
\left(\begin{matrix}0.0 & 1.0 & 2.0 & 3.0\\\\4.0 & 5.0 & 6.0 & 7.0\end{matrix}\right) \rightarrow
\left(\begin{matrix}16.0 & 26.0 & 40.0 & 58.0\end{matrix}\right)
$$
##### 张量归约取平方和操作的调用
NiuTrans.Tensor提供了张量的ReduceSumSquared操作，调用方法为：
```C++
void ReduceSumSquared(const XTensor &input, XTensor &output, int dim, const XTensor &shift);
XTensor ReduceSumSquared(const XTensor &input, int dim, const XTensor &shift);
```
ReduceSumSquared用来计算张量的沿着某一维度元素的方差，张量归约取方差操作的参数说明如下所示:
Parameters:
* input - 输入张量
* output - 输出张量
* dim - 沿着指定维度进行取平均值操作
* shift - 输入的偏移
* input(XTensor) - 输入张量
* output(XTensor，optional) - 输出张量
* dim(int) - 沿着指定维度进行取平均值操作
* shift(XTensor) - 输入的偏移
##### 张量归约取方差片段示例
##### 张量归约取平方和片段示例
调用ReduceSumSquared进行张量归约取方差操作的示例代码如下所示：
调用ReduceSumSquared进行张量归约取平方和操作的示例代码如下所示：
```
/* call reduce sum squared function */
t = ReduceSumSquared(*s, 0, *shift);
```
有关张量归约取方差的详细代码示例见：
有关张量归约取平方和的详细代码示例见：
NiuTrans.Tensor/Tensor/test/TReduceSumSquared.cpp
#### 归约取标准差（ReduceVariance）
#### 归约取方差（ReduceVariance）
##### 什么是张量的归约取标准差操作？
##### 什么是张量的归约取方差操作？
张量的归约取标准差操作是沿着张量的某一维度，计算该张量在该维度的标准差,一个\\(2 \times 4\\)的张量在维度0进行取标准差操作的过程如下所示：
张量的归约取方差操作是沿着张量的某一维度，计算该张量在该维度的标准差,一个\\(2 \times 4\\)的张量在维度0进行取标准差操作的过程如下所示：
$$
\left(\begin{matrix}0.0 & 1.0 & 2.0 & 3.0\\\\4.0 & 5.0 & 6.0 & 7.0\end{matrix}\right) \rightarrow
\left(\begin{matrix}4.0 & 4.0 & 4.0 & 4.0\end{matrix}\right)
\left(\begin{matrix}8.0 & 4.0 & 4.0 & 4.0\end{matrix}\right)
$$
##### 张量归约取标准差操作的调用
##### 张量归约取方差操作的调用
NiuTrans.Tensor提供了张量的ReduceVariance操作，调用方法为：
```
```C++
void _ReduceVariance(const XTensor * input, XTensor * output, int dim, const XTensor * mean)
XTensor ReduceVariance(const XTensor &input, int dim, const XTensor &mean)
```
ReduceVariance用来计算张量的沿着某一维度元素的标准差，张量归约取标准差操作的参数说明如下所示:
ReduceVariance用来计算张量的沿着某一维度元素的方差，张量归约取方差操作的参数说明如下所示:
Parameters:
* input - 输入张量
* output - 输出张量
* dim - 沿着指定维度进行取标准差操作
* mean - 均值
* input(XTensor) - 输入张量
* output(XTensor，optional) - 输出张量
* dim(int) - 沿着指定维度进行取标准差操作
* mean(XTensor) - 均值
##### 张量归约取标准差片段示例
##### 张量归约取方差片段示例
调用ReduceVariance进行张量归约取标准差操作的示例代码如下所示：
调用ReduceVariance进行张量归约取方差操作的示例代码如下所示：
```
/* call reduce variance function */
t = ReduceVariance(*s, 0, *mean);
```
有关张量归约取标准差的详细代码示例见：
有关张量归约取方差的详细代码示例见：
NiuTrans.Tensor/Tensor/test/TReduceVariance.cpp
......@@ -1378,8 +1500,9 @@ NiuTrans.Tensor/Tensor/test/TReduceVariance.cpp
张量间的级联操作是沿着张量的某一维度，将一系列张量或是一个列表中的所有张量连接在一起组成一个更大的张量，将维度分别为\\(2 \times 1\\)和\\(2 \times 2\\)的两个张量进行级联过程如下所示：
$$
\left(\begin{matrix}0.0\\\\1.0\end{matrix}\right) +
\left(\begin{matrix}2.0 & 3.0\\\\4.0 & 5.0\end{matrix}\right) \rightarrow
Concatenate \left[ \left(\begin{matrix}0.0\\\\1.0\end{matrix}\right) ,
\left(\begin{matrix}2.0 & 3.0\\\\4.0 & 5.0\end{matrix}\right) \right]
\rightarrow
\left(\begin{matrix}0.0 & 2.0 & 3.0\\\\1.0 & 4.0 & 5.0\end{matrix}\right)
$$
......@@ -1388,29 +1511,29 @@ $$
NiuTrans.Tensor提供了张量间的级联操作，调用方法为：
第一种调用方法中的操作对象是列表，将进行级联操作的张量存入列表smalls中，级联结果存入张量big中：
```
void _Concatenate(const XList * smalls, XTensor * big, int dim)
```C++
void Concatenate(const XList &smalls, XTensor &big, int dim)
XTensor Concatenate(const XList &smalls, int dim)
```
Parameters:
* smalls - 进行级联张量的列表
* big - 输出张量
* dim - 在指定维度进行级联
* smalls(XList) - 进行级联张量的列表
* big(XTensor, optional) - 输出张量
* dim(int) - 在指定维度进行级联
第二种方法操作对象不再是列表中的张量而是直接对一系列张量进行级联操作：
```
void _Concatenate(const XTensor * smallA, const XTensor * smallB, XTensor * big, int dim)
```C++
void Concatenate(const XTensor &smallA, const XTensor &smallB, XTensor &big, int dim)
XTensor Concatenate(const XTensor &smallA, const XTensor &smallB, int dim)
```
Parameters:
* smallA - 输入张量1
* smallB - 输入张量2
* big - 输出张量
* dim - 进行级联的维度
* smallA(XTensor) - 输入张量1
* smallB(XTensor) - 输入张量2
* big(XTensor, optional) - 输出张量
* dim(int) - 进行级联的维度
##### 张量级联片段示例
......@@ -1459,29 +1582,34 @@ $$
NiuTrans.Tensor提供了张量的合并操作，调用方法为：
在第一种调用方法中是将源张量中的某一维度进行Merge操作，Merge结果为张量t，whereToMerge为指定进行Merge操作的维度，leadingDim为指定将哪一维度Merge，例如：(N/2, 2, M) -> (N, M)，参数说明如下表所示:
```
void _Merge(const XTensor * s, XTensor * t, int whereToMerge, int leadingDim = -1)
```C++
void Merge(const XTensor &s, XTensor &t, int whereToMerge, int leadingDim = -1);
XTensor Merge(const XTensor &s, int whereToMerge, int leadingDim = -1)
void Merge(const XTensor &smallA, const XTensor &smallB, XTensor &t, int whereToMerge);
XTensor Merge(const XTensor &s, int whereToMerge, int leadingDim = -1);
XTensor Merge(const XTensor &smallA, const XTensor &smallB, int whereToMerge);
```
Parameters:
* s - 输入张量
* t - 输出张量
* whereToMerge - 沿着指定维度进行Merge操作
* leadingDim - 把指定维度进行Merge操作
* s(smallA)(XTensor) - 输入张量(1)
* smallB(XTensor, optional) - 输入张量2
* t(XTensor, optional) - 输出张量
* whereToMerge(int) - 沿着指定维度进行Merge操作
* leadingDim(int, optional) - 把指定维度进行Merge操作，默认为-1
在第二种调用方法中是将所操作张量存入列表smalls中，操作结果为张量big，whereToMerge为指定进行Merge操作的维度，例如：2 * (N/2, M) -> (N, M)，参数说明如下表所示:
在第二种调用方法中是将所操作张量存入列表smalls中，操作结果为张量t，whereToMerge为指定进行Merge操作的维度，例如：2 * (N/2, M) -> (N, M)，参数说明如下表所示:
```
void _Merge(const XList * smalls, XTensor * big, int whereToMerge)
void Merge(const XList &smalls, XTensor &big, int whereToMerge)
XTensor Merge(const XList &smalls, int whereToMerge)
```
Parameters:
* smalls - 存放进行合并张量的列表
* big - 结果张量
* whereToMerge - 沿着指定维度进行Merge操作
* smalls(XList) - 存放进行合并张量的列表
* big(XTensor, optional) - 输出张量
* whereToMerge(int) - 沿着指定维度进行Merge操作
##### 张量合并片段示例
......@@ -1500,6 +1628,33 @@ t = Merge(*sList, 0);
NiuTrans.Tensor/Tensor/test/TMerge.cpp
#### 变形（Reshape）
张量的变形操作是将张量改变形状的操作。将维度为\\(6\\)的张量变换为\\(2 \times 3\\)的张量过程如下所示：
$$
\left(\begin{matrix}0.0 & 1.0 & 2.0 & 3.0 & 4.0 & 5.0\end{matrix}\right)
\rightarrow
\left(\begin{matrix}0.0 & 1.0 & 2.0\\\\3.0 & 4.0 & 5.0\end{matrix}\right)
$$
##### 张量变形的调用
NiuTrans.Tensor提供了张量间的级联操作，调用方法为：
```C++
void Reshape(XTensor &s, XTensor &t, int order, int * dimSize);
XTensor Reshape(XTensor &s, int order, int * dimSize);
```
Parameters:
* s(XTensor) - 输入张量
* t(XTensor, optional) - 输出张量
* order(int) - 张量的阶数
* dimsize(int) - 维度大小
##### 张量切分片段示例
#### 切分（Split）
##### 什么是张量的切分操作？
......@@ -1513,7 +1668,7 @@ $$
\begin{aligned}
\Biggl( & \left(
\begin{matrix}0.0 & 1.0 & 2.0\\\\3.0 & 4.0 & 5.0\end{matrix}\right),
\\\\ & \left(
& \left(
\begin{matrix}0.1 & 1.1 & 2.1\\\\3.1 & 4.1 & 5.1\end{matrix}
\right) \Biggr)
\end{aligned}
......@@ -1531,34 +1686,33 @@ $$
NiuTrans.Tensor提供了两种张量切分操作，调用方法为：
在第一种调用方法中是将源张量中的某一维度进行Split操作，Split结果为张量t，whereToSplit为在哪一维度进行split操作，splitNum表示分成多少份，例如：(N, M) -> (N/3, M, 3)，参数说明如下所示:
```
void _Split(const XTensor * s, XTensor * t, int whereToSplit, int splitNum)
```C++
void Split(const XTensor &s, XTensor &t, int whereToSplit, int splitNum);
XTensor Split(const XTensor &s, int whereToSplit, int splitNum)
XTensor Split(const XTensor &s, int whereToSplit, int splitNum);
```
Parameters:
* s - 输入张量
* t - 输出张量
* whereToSplit - 在指定维度进行split操作
* splitNum - 分成多少份
* s(XTensor) - 输入张量
* t(XTensor, optional) - 输出张量
* whereToSplit(int) - 在指定维度进行split操作
* splitNum(int) - 分成多少份
在第二种调用方法中是将所操作张量big按某一维度whereToSplit进行Split操作，操作结果为包含若干更小维度张量的列表smalls，splitNum表示分成多少份，例如：(N, M) -> 2 * (N/2, M)，参数说明如下所示:
```
void _Split(const XTensor * big, XList * smalls, int whereToSplit, int splitNum)
```C++
void Split(const XTensor &big, TensorList &smalls, int whereToSplit, int splitNum);
XList SplitList(const XTensor &big, int whereToSplit, int splitNum)
```
Parameters:
* big - 输入张量
* smalls - 存放切分出张量的列表
* whereToSplit - 在指定维度进行split操作
* splitNum - 分成多少份
* big(XTensor) - 输入张量
* smalls(TensorList, optional) - 存放切分出张量的列表
* whereToSplit(int) - 在指定维度进行split操作
* splitNum(int) - 分成多少份
##### 张量切分片段示例
上述第一种张量切分片段示例如下所示，s为进行切分的张量，t为结果张量，0表示沿着维度0进行切分操作，2表示切分份数为2：
上述第一种张量切分片段示例如下所示，s为切分的张量，t为结果张量，0表示沿着维度0进行切分操作，2表示切分份数为2：
```
/* call split function */
......@@ -1576,11 +1730,58 @@ Split(*s, tList, 1, 2);
NiuTrans.Tensor/Tensor/test/TSplit.cpp
#### Squeeze
##### 什么是Squeeze？
Squeeze的作用是通过对张量进行压缩操作，返回一个新的在指定维度删除该维度的张量，这个返回的张量与源张量共享相同的基础数据，
#### 张量维度转换（Transpose）
##### 什么是张量维度转换？
张量的维度转换操作将输入张量的指定维度进行调换,一个\\(3 \times 2\\)的张量进行Transpose操作后变为\\(2 \times 3\\)的张量，如下所示：
$$
\left(\begin{matrix}0.0 & 1.0 & 2.0\\\\3.0 & 4.0 & 5.0\end{matrix}\right) \rightarrow
\left( \begin{matrix}0.0 & 3.0\\\\ 1.0 & 4.0 \\\\ 2.0 & 5.0\end{matrix}\right)
$$
##### Transpose的调用
NiuTrans.Tensor提供了张量的Transpose操作，调用方法及参数说明如下所示:
```C++
void Transpose(const XTensor &a, XTensor &b, const int i, const int j);
XTensor Transpose(const XTensor &a, const int i, const int j);
```
Parameters:
a(XTensor) - 输入张量
b(XTensor， optional) - 输出张量
i(int) - 进行操作的维度1
j(int) - 进行操作的维度2
##### Transpose片段示例
Transpose示例代码如下，其中s为输入的待操作张量，t1、t2代表输出结果张量，以下两行分别表示在维度1和维度2上插入的维度大小为2：
```
/* call Unsqueeze function */
t1 = Unsqueeze(*s, 1, 2);
t2 = Unsqueeze(*s, 2, 2);
```
有关张量Transpose的详细代码示例见：
NiuTrans.Tensor/Tensor/test/TTranspose.cpp
#### Unsqueeze
##### 什么是Unsqueeze？
Unsqueeze的作用是通过对张量进行操作，返回一个新的在指定维度插入新维度的张量，这个返回的张量与源张量共享相同的基础数据，一个\\(2 \times 3\\)的张量在维度1和2分别进行Unsqueeze的操作如下所示，插入新的维度大小均为2：
Unsqueeze的作用是通过对张量进行拓展操作，返回一个新的在指定维度插入新维度的张量，这个返回的张量与源张量共享相同的基础数据，一个\\(2 \times 3\\)的张量在维度1和2分别进行Unsqueeze的操作如下所示，插入新的维度大小均为2：
$$
\left(\begin{matrix}0.0 & 1.0 & 2.0\\\\3.0 & 4.0 & 5.0\end{matrix}\right) \rightarrow
......@@ -1608,16 +1809,16 @@ $$
NiuTrans.Tensor提供了张量的Unsqueeze操作，调用方法及参数说明如下所示:
```
void _Unsqueeze(const XTensor * a, XTensor * b, int dim, int dSize)
void Unsqueeze(const XTensor &a, XTensor &b, int dim, int dSize)
XTensor Unsqueeze(const XTensor &a, int dim, int dSize)
```
Parameters:
* a - 输入张量
* b - 输出张量
* dim - 在指定维度进行Unsqueeze操作
* dSize - 插入维度的大小
* a(XTensor) - 输入张量
* b(XTensor, optional) - 输出张量
* dim(int) - 在指定维度进行Unsqueeze操作
* dSize(int) - 插入维度的大小
##### Unsqueeze片段示例
......@@ -1652,20 +1853,20 @@ $$
NiuTrans.Tensor提供了张量的Sort操作，调用方法及参数说明如下所示:
```
void _Sort(const XTensor * a, XTensor * b, XTensor * index, int dim)
```C++
void Sort(const XTensor &a, XTensor &b, XTensor &index, int dim);
void _SortMe(XTensor * a, XTensor * index, int dim)
void SortMe(XTensor &a, XTensor &index, int dim);
void Sort(XTensor & a, XTensor & b, XTensor & index, int dim)
void Sort(XTensor & a, XTensor & b, XTensor & index, int dim);
```
Parameters:
* a - 输入张量
* b- 输出张量
* index - 输出张量中元素的索引
* dim - 沿着指定维度进行Sort操作
* a(XTensor) - 输入张量
* b(XTensor, optional) - 输出张量
* index(int) - 输出张量中元素的索引
* dim(int) - 沿着指定维度进行Sort操作
##### Sort片段示例
......@@ -1676,7 +1877,9 @@ Sort蝷箔誨蝷綽銝箄ndex銝箇
Sort(*a, b, *index, 0)
```
有关Sort的详细代码示例见 NiuTrans.Tensor/Tensor/test/TSort.cpp
有关Sort的详细代码示例见：
NiuTrans.Tensor/Tensor/test/TSort.cpp
#### TopK
......@@ -1698,19 +1901,19 @@ $$
NiuTrans.Tensor提供了张量的TopK操作，调用方法及参数说明如下所示:
```
void _TopK(const XTensor * a, XTensor * b, XTensor * index, int dim, int k)
```C++
void TopK(const XTensor &a, XTensor &b, XTensor &index, int dim, int k)
void TopK(XTensor &a, XTensor &b, XTensor &index, int dim, int k)
```
Parameters:
* a - 输入张量
* b - 输出张量
* index - 输出结果索引
* dim - 沿着指定维度进行TopK操作
* k - TopK中k代表取最大的k个值
* a(XTensor) - 输入张量
* b(XTensor, optional) - 输出张量
* index(XTensor) - 输出结果索引
* dim(int) - 沿着指定维度进行TopK操作
* k(int) - TopK中k代表取最大的k个值
##### TopK片段示例
......@@ -1723,7 +1926,9 @@ int k = inputDimSize[dim];
TopK(s, t, index, dim, k);
```
有关TopK的详细代码示例见 NiuTrans.Tensor/Tensor/test/TTopK.cpp
有关TopK的详细代码示例见:
NiuTrans.Tensor/Tensor/test/TTopK.cpp
### 激活函数(function)
......@@ -1740,18 +1945,18 @@ Dropout銝蝘瘛勗漲摮虫憓葉摨迤閫挾嚗
NiuTrans.Tensor提供了张量的Dropout激活函数，调用方法及参数说明如下所示:
```
void _Dropout(const XTensor * x, XTensor * y, unsigned int seed, DTYPE dropProb, int leadingDim = -1)
void Dropout(const XTensor &x, XTensor &y, unsigned int seed, DTYPE dropProb, int leadingDim = -1);
XTensor Dropout(const XTensor &x, DTYPE dropProb, int leadingDim = -1)
XTensor Dropout(const XTensor &x, DTYPE dropProb, int leadingDim = -1);
```
Parameters:
* x - 输入张量
* y - 输出张量
* seed - 随机种子
* dropProb - 随机将单元隐藏的概率
* leadingDim - 沿着指定维度进行操作
* x(XTensor) - 输入张量
* y(XTensor, optional) - 输出张量
* seed(int) - 随机种子
* dropProb(DTYPE) - 随机将单元隐藏的概率
* leadingDim(int) - 沿着指定维度进行操作，默认为-1
##### Dropout片段示例
......@@ -1771,24 +1976,24 @@ NiuTrans.Tensor/Tensor/test/TDropout.cpp
##### 什么是HardTanH？
HardTanH是一种激活函数，HardTanH函数定义为：
>y = 1 &nbsp;&nbsp;if x > 1 <br />
> y = 1 &nbsp;&nbsp;if x > 1 <br />
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; x &nbsp;&nbsp;if -1 <= x <= 1 <br />
&nbsp;&nbsp; &nbsp; -1 &nbsp;&nbsp;if x < -1
&nbsp;&nbsp; &nbsp; -1 &nbsp;&nbsp;if x < -1
##### HardTanH调用
NiuTrans.Tensor提供了张量的HardTanH激活函数，调用方法及参数说明如下所示:
```
void _HardTanH(const XTensor * x, XTensor * y)
void HardTanH(const XTensor &x, XTensor &y);
XTensor HardTanH(const XTensor &x)
XTensor HardTanH(const XTensor &x);
```
Parameters:
* x - 输入张量
* y - 输出张量
* x(XTensor) - 输入张量
* y(XTensor, optional) - 输出张量
##### HardTanH片段示例
......@@ -1815,15 +2020,15 @@ Identity銝蝘瘣餃嚗dentity摰蛹嚗
NiuTrans.Tensor提供了张量的Identity激活函数，调用方法及参数说明如下所示:
```
void _Identity(const XTensor * x, XTensor * y)
void Identity(const XTensor &x, XTensor &y);
XTensor Identity(const XTensor &x)
XTensor Identity(const XTensor &x);
```
Parameters:
* x - 输入张量
* y - 输出张量
* x(XTensor) - 输入张量
* y(XTensor, optional) - 输出张量
##### Identity片段示例
......@@ -1850,16 +2055,16 @@ LogSoftmax銝蝘瘣餃嚗ogSoftmax摰蛹嚗
NiuTrans.Tensor提供了张量的LogSoftmax激活函数，调用方法及参数说明如下所示:
```
void _LogSoftmax(const XTensor * x, XTensor * y, int leadDim)
void LogSoftmax(const XTensor &x, XTensor &y, int leadDim);
XTensor LogSoftmax(const XTensor &x, int leadDim)
XTensor LogSoftmax(const XTensor &x, int leadDim);
```
Parameters:
* x - 输入张量
* y - 输出张量
* leadDim - 沿着指定维度进行操作
* x(XTensor) - 输入张量
* y(XTensor, optional) - 输出张量
* leadDim(int) - 沿着指定维度进行操作
##### LogSoftmax片段示例
......@@ -1874,50 +2079,6 @@ y = LogSoftmax(*x, 1);
NiuTrans.Tensor/Tensor/test/TLogSoftmax.cpp
#### Loss
##### 什么是Loss？
Loss Function(损失函数)是用来衡量神经网络模型效果及优化目标的一种损失函数，函数定义为：
>squared error : loss = sum_{i} 0.5*(gold_i - output_i)^2 <br />
cross entropy : loss = sum_{i} (-gold_i * log(output_i)) <br />
one hot error : loss = sum_{i} e_i <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; where e_i = 0.5*(t_i - y_i)^2 &nbsp;&nbsp;if t_i = 1, <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;e_i = 0 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; otherwise
##### Loss调用
NiuTrans.Tensor提供了张量的Loss激活函数，调用方法及参数说明如下所示:
```
DTYPE _LossCompute(XTensor * gold, XTensor * output, LOSS_FUNCTION_NAME LFName, bool isLogOutput, int leadDim, int gBeg, int gLen, int oBeg)
```
Parameters:
* gold - 标准答案
* output - 输出的模型预测结果
* LFName - 损失函数名称，目前支持SQAREDERROR, CROSSENTROPY, ONTHOTERROR
* isLogOutput - 输出是否log
* leadDim - 沿着指定维度进行输出
* gBeg - 沿着指定维度leadDim从指定位置取标准答案
* gLen - 从指定位置gBeg开始标准答案的偏移
* oBeg - 沿着指定维度leadDim从指定位置开始输出模型预测结果
##### Loss片段示例
Loss示例代码如下所示：
```
/* call LossCompute function */
error = _LossCompute(gold, output, SQUAREDERROR, false, 0, 0, dimSize[0], 0);
```
有关Loss的详细代码示例见：
NiuTrans.Tensor/Tensor/test/TLoss.cpp
#### Rectify
##### 什么是Rectify？
......@@ -1930,16 +2091,15 @@ Rectify銝蝘瘣餃嚗ectify摰蛹嚗
NiuTrans.Tensor提供了张量的Rectify激活函数，调用方法及参数说明如下所示:
```
void _Rectify(const XTensor * x, XTensor * y)
void Rectify(const XTensor &x, XTensor &y);
XTensor Rectify(const XTensor &x)
XTensor Rectify(const XTensor &x);
```
Parameters:
* x - 输入张量
* y - 输出张量
* x(XTensor) - 输入张量
* y(XTensor, optional) - 输出张量
##### Rectify片段示例
......@@ -1963,14 +2123,14 @@ Sigmoid銝蝘瘣餃嚗igmoid摰蛹嚗
NiuTrans.Tensor提供了张量的Sigmoid激活函数，调用方法及参数说明如下所示:
```
void _Sigmoid(const XTensor * x, XTensor * y)
void Sigmoid(const XTensor &x, XTensor &y);
XTensor Sigmoid(const XTensor &x)
XTensor Sigmoid(const XTensor &x);
```
Parameters:
* x - 输入张量
* y - 输出张量
* x(XTensor) - 输入张量
* y(XTensor, optional) - 输出张量
##### Sigmoid片段示例
......@@ -1994,15 +2154,15 @@ Softmax銝蝘瘣餃嚗oftmax摰蛹嚗
NiuTrans.Tensor提供了张量的Softmax激活函数，调用方法及参数说明如下所示:
```
void _Softmax(const XTensor * x, XTensor * y, int leadDim)
void Softmax(const XTensor &x, XTensor &y, int leadDim);
XTensor Softmax(const XTensor &x, int leadDim)
XTensor Softmax(const XTensor &x, int leadDim);
```
Parameters:
* x - 输入张量
* y - 输出张量
* leadDim - 沿着指定维度进行操作
* x(XTensor) - 输入张量
* y(XTensor, optional) - 输出张量
* leadDim(int) - 沿着指定维度进行操作
##### Softmax片段示例
......@@ -2096,7 +2256,7 @@ delete mem;
关于矩阵乘法的详细代码请见NiuTrans.Tensor/Tensor/sample/mul/。
```
```C++
#include "mul.h"
namespace nts
......@@ -2176,7 +2336,7 @@ void sampleMUL1()
前馈神经网络语言模型的主要流程如下所示:
```
```C++
int FNNLMMain(int argc, const char ** argv)
{
if(argc == 0)
......@@ -2215,7 +2375,7 @@ int FNNLMMain(int argc, const char ** argv)
对模型中的参数进行初始化：
```
```C++
/* initialize the model */
void Init(FNNModel &model)
{
......@@ -2256,7 +2416,7 @@ void Init(FNNModel &model)
训练过程：
```
```C++
void Train(const char * train, bool isShuffled, FNNModel &model)
{
char name[MAX_NAME_LENGTH];
......@@ -2402,7 +2562,7 @@ void Train(const char * train, bool isShuffled, FNNModel &model)
前向过程代码如下：
```
```C++
/*
forward procedure
>> inputs - input word representations
......@@ -2512,7 +2672,7 @@ void Forward(XTensor inputs[], XTensor &output, FNNModel &model, FNNNet &net)
反向以及反向传播后的更新代码如下：
```
```C++
/*
backward procedure
>> inputs - input word representations
......@@ -2633,8 +2793,6 @@ void Backward(XTensor inputs[], XTensor &output, XTensor &gold, LOSS_FUNCTION_NA
}
```
## 实例3：循环神经网络
## NiuTrans.Tensor团队
* 肖桐
......@@ -2644,96 +2802,4 @@ void Backward(XTensor inputs[], XTensor &output, XTensor &gold, LOSS_FUNCTION_NA
* 林野
* 张裕浩
* 胡驰
NiuTrans.Tensor张量计算库由东北大学自然语言处理实验室小牛开源团队开发，成员来自东北大学自然语言处理实验室、小牛翻译、小牛雅智，致力于为深度学习相关研究及工业系统的开发提供完整的张量定义及计算功能。
## 附录
在XTensor.h头文件中定义的成员变量说明：
| 成员变量 | 功能 |
| - | - |
| int id | 张量标识 |
| XMem * mem | 张量所使用的内存池 |
| void * data | 保存元素的数据数组 |
| void * dataHost | 主机内存上的数据副本，只在GPU上运行时被激活 |
| void ** dataP | 指向数据地址的指针 |
| int devID | 设备ID，指张量所申请的空间所在CPU或者GPU设备的编号，-1表示CPU |
| int order | 张量的维度，例如：一个矩阵（维度为2）是一个二维张量 |
| int dimSize[ ] | 张量中每一维度的大小，索引0表示第1维 |
| int dimSizeRDI[ ] | 转置模式下张量中每一维度的大小，索引0表示第1维 |
| TENSOR_DATA_TYPE dataType | 每个数据单元的数据类型 |
| int unitSize | 数据单元的大小，类似于sizeof() |
| int unitNum | 数据单元的数量 |
| bool isSparse | 是否稠密，一个n * m稠密矩阵的数据量大小为n * m,而稀疏（非稠密）矩阵的数据量大小则取决于矩阵中非零元素个数。|
| int unitNumNonZero | 稀疏矩阵中非零元素个数 |
| float denseRatio | 稠密度，指非零单元的比例，是介于0和1之间的一个实数，0表示所有单元全为零，1表示全为非零单元。|
| bool isShared | 标志数据数组是否被其他张量所共享 |
| bool isDefaultDType | 矩阵中使用的数据类型是否是属于默认数据类型 |
| bool isInGlobalMem | 标志数据是否在全局内存而不是内存池中 |
| bool isAllValued[ ] | 标志稀疏矩阵中是否每个维度都具有非零元素 |
| bool isInit | 张量是否被初始化 |
| bool isTmp | 张量是否为临时创建 |
| bool isGrad | 当使用模型参数时张量是否保持梯度 |
| unsigned int visitMark | 节点访问标志 |
| XTensor * grad | 反向传播的梯度 |
| XLink income | 超边的入边 |
| XLink outgo | 超边的出边 |
在XTensor.h头文件中定义的方法说明：
| 功能 | 函数 | 参数 |
| - | - | - |
| 构造函数 | XTensor() | N/A |
| 析构函数 | ~XTensor() | N/A |
| 初始化成员变量 | void Init() | N/A |
| 销毁数据 | void DestroyData() | N/A |
| 张量的浅层复制 | void ShallowCopy(<br>const XTensor &tensor) | tensor - 进行复制的张量 |
| 重载等于符号 | XTensor& operator= (<br>const XTensor &tensor) | tensor - 重载的张量 |
| 重载加法符号 | XTensor operator+ (<br>const XTensor &tensor) | tensor - 重载的张量 |
| 重载乘法符号 | XTensor operator* (<br>const XTensor &tensor) | tensor - 重载的张量 |
| 线性变换 | XTensor Lin(<br>DTYPE scale, DTYPE shift = 0) | scale - 缩放参数 <br> shift - 偏移参数 |
| 判断两个张量数据类型<br>和大小是否相同 | static bool IsIdentical(<br> XTensor * a, XTensor * b) | a - 进行比较的第一个张量 <br> b - 进行比较的第二个张量 |
| 判断三个张量数据类型<br>和大小是否相同 | static bool IsIdentical(<br> XTensor * a, XTensor * b, XTensor * c) | a - 进行比较的第一个张量 <br> b - 进行比较的第二个张量 <br> c - 进行比较的第三个张量 |
| 设置张量每一维度的大小 | void SetDim(<br>int * myDimSize) |myDimSize - 张量每一维度的大小 |
| 得到张量中给定的维度大小 | int GetDim(<br>const int dim) | dim - 张量的维度 |
| 重新调整矩阵维度 | void Reshape(<br> const int order, const int * myDimSize) | order - 张量的维度 <br> myDimSize - 张量每一维的大小 |
| 得到张量中元素数量 | int GetSize() | N/A |
| 得到内存使用大小 | int GetDataSizeInChar() | N/A |
| 得到所给数据类型的数据<br> 单元大小 | int GetUnitSize(<br> TENSOR_DATA_TYPE myDataType) | myDataType - 所给数据类型 |
| 张量中所有元素设置为0 | void SetZeroAll(XStream * stream = NULL) | stream - 多线程流|
| 用数组赋值张量 | void SetData(<br> const void * d, int num, int beg = 0) | d - 赋值数组 <br> num - 数组大小 <br> beg - 赋值时从张量的第几位开始 |
| 设置张量服从均匀分布 | void SetDataRand(<br> DTYPE lower, DTYPE upper) | lower - 最小值 <br> upper - 最大值 |
| 设置张量服从正态分布 | void SetDataRandn(<br> DTYPE mean, DTYPE standardDeviation) | mean - 均值 <br> standardDeviation - 标准差 |
| 检查张量中元素是否相同 | bool CheckData(<br> const void * answer, int num, int beg = 0) | answer - 给定数组 <br> num - 数组大小 <br> beg - 赋值时从张量的第几位开始 |
| 设置数据指针 | void SetDataPointer() | N/A |
| 将给定维度中元素<br> 设置为升序 | void SetAscendingOrder(<br>int dim) | dim - 给定维度 |
| 得到索引指向的单元的值 | DTYPE Get(int index[], int size = -1) | index - 给定索引 <br> size-矩阵大小 |
| 获取张量中元素指针 | void * GetCell(<br>int * index, int size) | index - 元素位置 <br> size-矩阵大小 |
| 获取一维张量中元素的<br>默认类型值 | DTYPE Get1D(<br>int i) | i - 第一维 |
| 获取二维张量中元素的<br>默认类型值 | DTYPE Get2D(<br>int ni, int mi) const | ni - 第一维 <br> mi - 第二维 |
| 获取三维张量中元素的<br>默认类型值 | DTYPE Get3D(<br>int d0, int d1, int d2) | d0 - 第一维 <br> d1 - 第二维 <br> d2 - 第三维 |
| 获取一维张量中元素的<br>整形值 |int Get1DInt(<br>int i) | i - 第一维 |
| 获取二维张量中元素的<br>整形值 | int Get2DInt(<br>int ni, int mi) | ni - 第一维 <br> mi - 第二维 |
| 获取三维张量中元素的整形值 | int Get3DInt(<br>int d0, int d1, int d2) | d0 - 第一维 <br> d1 - 第二维 <br> d2 - 第三维 |
| 获取稀疏张量的值 | DTYPE GetInSparse(int i) | i - 稀疏矩阵中非0元素位置 |
| 获取稀疏张量中<br> 元组的键值 | int GetKeyInSparse(int i) | i - 稀疏矩阵中非0元素位置 |
| 设置单元中的值 | bool Set(<br>DTYPE value, int index[], int size = -1) | value - 值 <br> index - 元素位置 <br> size-矩阵大小 |
| 设置一维张量中的单元值 | bool Set1D(<br>DTYPE value, int i) | value - 值 <br> i - 第一维 |
| 设置二维张量中的单元值 | bool Set2D(<br>DTYPE value, int ni, int mi) | value - 值 <br> ni - 第一维 <br> mi - 第二维 |
| 设置三维张量中的单元值 | bool Set3D(<br>DTYPE value, int d0, int d1, int d2) | value - 值 <br> d0 - 第一维 <br> d1 - 第二维 <br> d2 - 第三维 |
| 增加二维张量中<br> 的单元值 | bool Add2D(<br>DTYPE value, int ni, int mi = 0) | value - 单元值 <br> ni - 行值 <br> mi - 列值 |
| 获取稀疏矩阵中<br> 非零元素数量 | int GetNonzeroSize() | N/A |
| 设置张量为临时变量 | void SetTMP(<br>bool myIsTmp = true) | myIsTmp - 是否为临时变量 |
| 张量是否保持梯度 | void SetGrad(<br>bool myIsGrad = true) | myIsTmp - 是否保持梯度 |
| 将矩阵重置为特定大小 | bool Resize(<br> const int myOrder, <br> const int * myDimSize, <br> const TENSOR_DATA_TYPE myDataType = DEFAULT_DTYPE, <br> const float myDenseRatio = 1.0F) | myOrder - 张量的维度 <br> myDimSize - 张量每一维的大小,索引0表示第一维 <br> myDataType - 张量的数据类型 <br> myDenseRatio - 张量的稠密度，1表示稠密张量 |
| 将矩阵重置为特定大小<br>并不申请新空间 | bool ResizeWithNoData(<br> const int myOrder, <br> const int * myDimSize, <br> const TENSOR_DATA_TYPE myDataType = DEFAULT_DTYPE, <br> const float myDenseRatio = 1.0F) | myOrder - 张量的维度 <br> myDimSize - 张量每一维的大小,索引0表示第一维 <br> myDataType - 张量的数据类型 <br> myDenseRatio - 张量的稠密度，1表示稠密张量 |
| 将矩阵重置为<br> 另一矩阵大小 | bool Resize(<br> const XTensor * myTensor) | myTensor - 重置矩阵大小的参考矩阵 |
| 用二值搜索方法<br> 找到稀疏矩阵中元素 | bool BinarySearch(<br> int key, DTYPE &value, void * &position) | key - 稀疏矩阵中元素位置 <br> value - 元素值 <br> position - 元素坐标位置 |
| 将数据刷新到<br> 目标设备中 | void FlushToMem(XMem * targetMem) | targetMem - 目标设备 |
| 在全局内存中<br> 申请矩阵的内存空间 | static void AllocateData(<br> XTensor * matrix, <br> XMem * myMem = NULL, <br> bool useBuf = false) | matrix - 申请内存空间的矩阵 <br> myMem - 是否在内存池中申请空间 <br> useBuf - 是否使用缓冲区 |
| 在全局内存中<br> 释放矩阵的内存空间 | static void FreeData(<br> XTensor * matrix, <br> XMem * myMem = NULL, <br> bool useBuf = false) | matrix - 申请内存空间的矩阵 <br> myMem - 是否在内存池中申请空间 <br> useBuf - 是否使用缓冲区 |
| 在缓冲区创建张量 | XTensor * NewTensorBuf( <br> const int myOrder, <br> const int * myDimSize, XMem * myMem, <br> const TENSOR_DATA_TYPE myDataType = <br> X_FLOAT, const float myDenseRatio = 1.0F) | myOrder - 张量的维度 <br> myDimSize - 张量每一维的大小,索引0表示第一维 <br> myMem - 张量所使用的内存池 <br> myDataType - 张量的数据类型 <br> myDenseRatio - 张量的稠密度，1表示稠密张量 |
| 依据给定张量<br>复制一个新的张量 | XTensor * NewTensor(<br>XTensor * a, bool isFilledData = true) | a - 给定张量 <br> isFilledData - 是否申请张量中的数据空间 |
| 依据给定张量<br>释放数据空间 | void DelTensor(<br>const XTensor * tensor) | tensor - 给定张量 |
| 依据给定张量<br>在缓存中释放数据空间 | void DelTensorBuf(<br>const XTensor * tensor) | tensor - 给定张量 |
\ No newline at end of file
* 许诺
Markdown 格式
0% 或
您添加了 0 人 到此讨论。请谨慎行事。
请先完成此评论的编辑！
请 注册 或者 后发表评论