| # 张量(Tensor) |
| |
| 每个Tensor实例都是一个分配在特定Device实例上的多维数组。 Tensor实例存储了变量并提供了用户不可见的支持多种设备的代数操作。注意,用户需要确保除了拷贝之外的tensor操作都是在相同的设备上进行的。 |
| |
| Tensor的实现 |
| |
| SINGA有三种Tensor函数的实现,分别在不同设备上。 |
| |
| * `tensor_math_cpp.h` 用Cpp实现了CppCPU上的各种操作 |
| * `tensor_math_cuda.h` 用Cuda (和cuBLAS)实现了CudaGPU上的各种操作 |
| * `tensor_math_opencl.h` 用OpenCL实现了OpenclGPU上的各种操作 |
| |
| |
| ## PYTHON API |
| |
| 用法示例: |
| |
| ```python |
| import numpy as np |
| from singa import tensor |
| from singa import device |
| |
| # create a tensor with shape (2,3), default CppCPU device and float32 |
| x = tensor.Tensor((2, 3)) |
| x.set_value(0.4) |
| |
| # create a tensor from a numpy array |
| npy = np.zeros((3, 3), dtype=np.float32) |
| y = tensor.from_numpy(npy) |
| |
| y.uniform(-1, 1) # sample values from the uniform distribution |
| |
| z = tensor.mult(x, y) # gemm -> z of shape (2, 3) |
| |
| x += z # element-wise addition |
| |
| dev = device.get_default_device() |
| x.to_device(dev) # move the data to a gpu device |
| |
| r = tensor.relu(x) |
| |
| s = tensor.to_numpy(r) # tensor -> numpy array |
| ``` |
| |
| 有两种类型的tensor函数: |
| |
| **Tensor成员函数** |
| |
| 将会改变Tensor实例的状态 |
| |
| **Tensor模块化函数** |
| |
| 接受Tensor实例作为自变量以及返回Tensor实例 |
| |
| 每个Tensor实例在读取数据前都必须做初始化 |
| |
| --- |
| |
| ### class singa.tensor.Tensor(shape=None, device=None, dtype=0) |
| |
| 创建Py Tensor,封装了一个基于swig转换的CPP Tensor。 |
| 三个参数分别是Tensor的三个属性。 |
| |
| **参数:** |
| - **shape (list<int>)** – 一个列表的整形数据作为Tensor的形状。如果shape没有指定,将会创建一个伪Tensor。 |
| - **device** – swig转化的使用设备模块化的Device实例。 如果为None,默认的CPU设备将会被使用。 |
| - **dtype** – 数据类型。 目前,大多数操作仅支持kFloat32。 |
| |
| --- |
| |
| #### T() |
| |
| 浅拷贝。 |
| |
| **返回值:** 一个新Tensor,共享底层数据所占内存,但标记为该tensor的转置版本。 |
| |
| --- |
| |
| #### add_column(v) |
| |
| 对该Tensor每列加上一个tensor。 |
| |
| **参数:** |
| - **v (Tensor)** – 被作为一列加到原tensor的Tensor |
| |
| --- |
| |
| #### add_row(v) |
| |
| 对该tensor每行加一个tensor。 |
| |
| **参数:** |
| - **v (Tensor)** – 被作为行加到原tensor的Tensor |
| |
| --- |
| |
| #### bernoulli(p) |
| |
| 对每个元素,按照给定概率从0/1中取样。 |
| |
| **参数:** |
| - **p (float)** – 以概率p取样一个元素为1 |
| |
| --- |
| |
| #### clone() |
| |
| **返回值:** 一个新Tensor,是待拷贝Tensor的深拷贝 |
| |
| --- |
| |
| #### copy() |
| |
| 调用singa::Tensor的拷贝构造器进行浅拷贝。 |
| |
| --- |
| |
| #### copy_data(t) |
| |
| 从另一个Tensor实例拷贝数据。 |
| |
| **参数:** |
| - **t (Tensor)** – 源Tensor |
| |
| --- |
| |
| #### copy_from_numpy(np_array, offset=0) |
| |
| 从numpy数组中拷贝数据。 |
| |
| **参数:** |
| - **np_array** – 源numpy数组 |
| - **offset (int)** – 目标偏移 |
| |
| --- |
| |
| #### deepcopy() |
| |
| 同clone() |
| |
| **返回值:** 新Tensor |
| |
| --- |
| |
| #### div_column(v) |
| |
| 将Tensor每列除以v。 |
| |
| **参数:** |
| - **v (Tensor)** – 1维tensor,和源tensor的列长相同 |
| |
| --- |
| |
| #### div_row(v) |
| |
| 将Tensor每行除以v。 |
| |
| **参数:** |
| - **v (Tensor)** – 1维tensor,和源tensor的行长相同 |
| |
| --- |
| |
| #### gaussian(mean, std) |
| |
| 按照高斯分布对每个元素采样。 |
| |
| **参数:** |
| - **mean (float)** – 分布的均值 |
| - **std (float)** – 分布的标准差 |
| |
| --- |
| |
| #### is_empty() |
| |
| **返回值:** 根据tensor的形状,如果是空的返回True |
| |
| --- |
| |
| #### is_transpose() |
| |
| **返回值:** 如果内部数据被转置则返回True,否则返回False |
| |
| --- |
| |
| #### l1() |
| |
| **返回值:** L1 norm |
| |
| --- |
| |
| #### l2() |
| |
| **返回值:** L2 norm |
| |
| --- |
| |
| #### memsize() |
| |
| - **返回值:** 被分配给该tensor的Bytes数 |
| |
| --- |
| |
| #### mult_column(v) |
| |
| 将tensor每列和v做元素级别乘法。 |
| |
| **参数:** |
| - **v (Tensor)** – 1维tensor,同源tensor列长等长 |
| |
| --- |
| |
| #### mult_row(v) |
| |
| 将tensor每行和v做元素级别乘法。 |
| |
| **参数:** |
| - **v (Tensor)** – 1维tensor,同源tensor行长等长 |
| |
| --- |
| |
| #### ndim() |
| |
| **返回值:** tensor的维度 |
| |
| --- |
| |
| #### reset_like(t) |
| |
| 根据给定tensor重置源tensor形状,数据类型和设备。 |
| |
| **参数:** |
| - **t (Tensor)** – 需要重置的tensor |
| |
| --- |
| |
| #### set_value(x) |
| |
| 设置所有元素值为给定值。 |
| |
| **参数:** |
| - **x(float)** - 待设定的值 |
| |
| --- |
| |
| #### size() |
| |
| **返回值:** tensor中的元素个数 |
| |
| --- |
| |
| #### to_device(device) |
| |
| 将tensor中数据传到指定设备上。 |
| |
| **参数:** |
| - **device** - 从CudaGPU/CppCPU/OpenclGPU转换的swig设备 |
| |
| --- |
| |
| #### to_host() |
| |
| 将tensor数据传到默认的CppCPU设备上。 |
| |
| --- |
| |
| #### uniform(low, high) |
| |
| 从均匀分布中进行采样。 |
| |
| **参数:** |
| - **low (float)** – 下界 |
| - **high (float)** – 上界 |
| |
| --- |
| |
| #### singa.tensor.abs(t) |
| |
| **参数:** |
| - **t(Tensor)** - 输入tensor |
| |
| **返回值:** 一个新tensor,其元素值为y=abs(x),x是t中的元素 |
| |
| --- |
| |
| #### singa.tensor.add(lhs, rhs, ret=None) |
| |
| 元素级别加法。 |
| |
| **参数:** |
| - **lhs (Tensor)** – 左操作tensor |
| - **rhs (Tensor)** – 右操作tensor |
| - **ret (Tensor, optional)** – 如果不是空, 结果将被保存在其中;否则,一个新tensor会被创建以保存结果。 |
| |
| **返回值:** 新tensor |
| |
| --- |
| |
| #### singa.tensor.add_column(alpha, v, beta, M) |
| |
| 将v加到M的每个列向量, 定义M一列为m,m=alpha * v + beta * m |
| |
| **参数:** |
| - **alpha (float)** – v的系数 |
| - **v (Tensor)** – 1维tensor |
| - **beta (float)** – M的系数 |
| - **M (Tensor)** – 2维tensor |
| |
| **返回值:** M |
| |
| --- |
| |
| #### singa.tensor.add_row(alpha, v, beta, M) |
| |
| 将v加到M的每个行向量, 定义M一行为m,m=alpha * v + beta * m。 |
| |
| **参数:** |
| - **alpha (float)** – v的系数 |
| - **v (Tensor)** – 1维tensor |
| - **beta (float)** – M的系数 |
| - **M (Tensor)** – 2维tensor |
| |
| **返回值:** M |
| |
| --- |
| |
| #### singa.tensor.average(t, axis=None) |
| |
| **参数:** |
| - **t (Tensor)** – 输入Tensor |
| - **axis (int, optional)** – 如果为空,取所有元素的平均值;否则,取给定维度的元素平均值。0表示列均值,1表示行均值。 |
| |
| **返回值:** 如果axis是空,返回一个float值;否则,返回一个新tensor |
| |
| --- |
| |
| #### singa.tensor.axpy(alpha, x, y) |
| |
| 元素级别操作 y += alpha * x。 |
| |
| **参数:** |
| - **alpha (float)** – x的系数 |
| - **x (Tensor)** – 被加的tensor |
| - **y (Tensor)** – 原tensor |
| |
| **返回值:** y |
| |
| --- |
| |
| #### singa.tensor.bernoulli(p, t) |
| |
| 对每个元素生成一个二进制位。 |
| |
| **参数:** |
| - **p (float)** – each element is 1 with probability p; and 0 with 1 - p |
| - **t (Tensor)** – the results are put into t |
| |
| **返回值:** t |
| |
| --- |
| |
| #### singa.tensor.copy_data_to_from(dst, src, size, dst_offset=0, src_offset=0) |
| |
| 将数据从一个tensor实例拷贝到另一个tensor实例。 |
| |
| **参数:** |
| - **dst (Tensor)** – 目标Tensor |
| - **src (Tensor)** – 源Tensor |
| - **size (int)** – 拷贝元素数目 |
| - **dst_offset (int)** – 拷贝到dst元素在dst的起始偏移 |
| - **src_offset (int)** – 待拷贝的元素在src中的起始偏移 |
| |
| --- |
| |
| #### singa.tensor.div(lhs, rhs, ret=None) |
| |
| 元素级别的除法。 |
| |
| **参数:** |
| - **lhs (Tensor)** – 左操作tensor |
| - **rhs (Tensor)** – 右操作tensor |
| - **ret (Tensor, optional)** – 如果非空,将把结果写入;否则,创建一个新tensor并将结果写入 |
| |
| **返回值:** 存有运算结果的tensor |
| |
| --- |
| |
| #### singa.tensor.eltwise_mult(lhs, rhs, ret=None) |
| |
| 元素级别的乘法。 |
| |
| **参数:** |
| - **lhs (Tensor)** – 左操作tensor |
| - **rhs (Tensor)** – 右操作tensor |
| - **ret (Tensor, optional)** – 如果非空,将把结果写入;否则,创建一个新tensor并将结果写入 |
| |
| **返回值:** 保存运算结果的tensor |
| |
| --- |
| |
| #### singa.tensor.exp(t) |
| |
| **参数:** |
| - **t (Tensor)** – 输入tensor |
| |
| **返回值:** 新tensor,其中元素为 y = exp(x),x为t中元素 |
| |
| --- |
| |
| #### singa.tensor.from_numpy(np_array) |
| |
| 根据numpy数组的形状、数据类型和数值创建一个tensor。 |
| |
| **参数:** |
| - **np_array** – numpy数组 |
| |
| **返回值:** 分配在默认CppCPU设备上的tensor实例 |
| |
| --- |
| |
| #### singa.tensor.gaussian(mean, std, t) |
| |
| 按照给定高斯分布生成数值。 |
| |
| **参数:** |
| - **mean (float)** – 高斯分布的均值 |
| - **std (float)** – 高斯分布的标准差 |
| - **t (Tensor)** – 结果被存入t |
| |
| **返回值:** t |
| |
| --- |
| |
| #### singa.tensor.ge(t, x) |
| |
| 元素级别的比较,t >= x。 |
| |
| **参数:** |
| - **t (Tensor)** – 左操作数 |
| - **x (Tensor or float)** – 右操作数 |
| |
| **返回值:** 0.0f 或 t[i] >= x[i] ? 1.0f:0.0f |
| |
| **返回值类型:** tensor,每个元素为 t[i] >= x ? 1.0f |
| |
| --- |
| |
| #### singa.tensor.gt(t, x) |
| |
| 元素级别的比较,t > x。 |
| |
| **参数:** |
| - **t (Tensor)** – 左操作tensor |
| - **x (Tensor or float)** – 右操作tensor或数 |
| |
| **返回值:** 0.0f 或 t[i] > x[i] ? 1.0f:0.0f |
| |
| **返回值类型:** tensor,每个元素为 t[i] > x ? 1.0f |
| |
| --- |
| |
| #### singa.tensor.le(t, x) |
| |
| 元素级别的比较,t <= x。 |
| |
| **参数:** |
| - **t (Tensor)** – 左操作tensor |
| - **x (Tensor or float)** – 右操作tensor或数 |
| |
| **返回值:** 0.0f 或 t[i] <= x[i] ? 1.0f:0.0f |
| |
| **返回值类型:** tensor,每个元素为 t[i] <= x ? 1.0f |
| |
| --- |
| |
| #### singa.tensor.lt(t, x) |
| |
| 元素级别的比较,t < x。 |
| |
| **参数:** |
| - **t (Tensor)** – 左操作tensor |
| - **x (Tensor or float)** – 右操作tensor或数 |
| |
| **返回值:** 0.0f 或 t[i] < x[i] ? 1.0f:0.0f |
| |
| **返回值类型:** tensor,每个元素为 t[i] < x ? 1.0f |
| |
| --- |
| |
| #### singa.tensor.log(t) |
| |
| **参数:** |
| - **t (Tensor)** – 输入tensor |
| |
| **返回值:** 一个新tensor,其元素值为y = log(x),x是t中的元素 |
| |
| --- |
| |
| #### singa.tensor.mult(A, B, C=None, alpha=1.0, beta=0.0) |
| |
| 矩阵-矩阵或矩阵-向量乘法, 函数返回 C = alpha * A * B + beta * C。 |
| |
| **参数:** |
| - **A (Tensor)** – 2维Tensor |
| - **B (Tensor)** – 如果B是1维Tensor, 将调用GEMV做矩阵-向量乘法;否则将调用GEMM。 |
| - **C (Tensor, optional)** – 存储结果;如果为空,将创建新tensor存储结果。 |
| - **alpha (float)** – A * B 的系数 |
| - **beta (float)** – C 的系数 |
| |
| **返回值:** 保存运算结果的tensor |
| |
| --- |
| |
| #### singa.tensor.pow(t, x, out=None) |
| |
| **参数:** |
| - **t (Tensor)** – 输入tensor |
| - **x (float or Tensor)** – 如果x是浮点数 y[i] = t[i]^x; 否则 y[i]= t[i]^x[i] |
| - **out (None or Tensor)** – 如果非空,将存入结果;否则,将创建一个新tensor保存结果。 |
| |
| **返回值:** 保存运算结果的tensor |
| |
| --- |
| |
| #### singa.tensor.relu(t) |
| |
| **参数:** |
| - **t (Tensor)** – 输入tensor |
| |
| **返回值:** tensor,其中元素为 y = x 若x >0;否则y = 0,x为t中元素 |
| |
| --- |
| |
| #### singa.tensor.reshape(t, s) |
| |
| 改变tensor的形状。 |
| |
| **参数:** |
| - **t (Tensor)** – 待改变形状的tensor |
| - **s (list<int>)** – 新形状,体积和原tensor体积相同 |
| |
| **返回值:** 新tensor |
| |
| --- |
| |
| #### singa.tensor.sigmoid(t) |
| |
| **参数:** |
| - **t (Tensor)** – 输入tensor |
| |
| **返回值:** tensor,其中元素为 y = sigmoid(x),x为t中元素 |
| |
| --- |
| |
| #### singa.tensor.sign(t) |
| |
| **参数:** |
| - **t (Tensor)** – 输入tensor |
| |
| **返回值:** tensor,其中元素为 y = sign(x),x为t中元素 |
| |
| --- |
| |
| #### singa.tensor.sizeof(dtype) |
| |
| **返回值:** 依据core.proto中定义的SINGA数据类型,返回给定类型所占Byte数目 |
| |
| --- |
| |
| #### singa.tensor.softmax(t, out=None) |
| |
| 对tensor每行做SoftMax。 |
| |
| **参数:** |
| - **t (Tensor)** – 输入1维或2维tensor |
| - **out (Tensor, 可选)** – 如果非空,将存入结果 |
| |
| **返回值:** 保存操作结果的tensor |
| |
| --- |
| |
| #### singa.tensor.sqrt(t) |
| |
| **参数:** |
| - **t (Tensor)** – 输入tensor |
| |
| **返回值:** tensor,其中元素为 y = sqrt(x),x为t中元素 |
| |
| --- |
| |
| #### singa.tensor.square(t) |
| |
| **参数:** |
| - **t (Tensor)** – 输入tensor |
| |
| **返回值:** tensor,其中元素为 y = x * x,x为t中元素 |
| |
| --- |
| |
| #### singa.tensor.sub(lhs, rhs, ret=None) |
| |
| 元素级别的减法。 |
| |
| **参数:** |
| - **lhs (Tensor)** – 左操作tensor |
| - **rhs (Tensor)** – 右操作tensor |
| - **ret (Tensor, 可选)** – 如果非空,将存入结果;否则,将创建一个新tensor保存 |
| |
| **返回值:** 存放结果的tensor |
| |
| --- |
| |
| #### singa.tensor.sum(t, axis=None) |
| |
| 在给定的维度上求和。 |
| |
| **参数:** |
| - **t (Tensor)** – 输入Tensor |
| - **axis (int, 可选)** – 如果为空,将对所有元素求和;如果给定数值,将沿给定维度求和,比如:0 - 按列求和;1 - 按行求和。 |
| |
| **返回值:** 如果是对整体求和,返回一个浮点数;否则返回tensor |
| |
| --- |
| |
| #### singa.tensor.sum_columns(M) |
| |
| 按列求和。 |
| |
| **参数:** |
| - **M (Tensor)** – 输入的2维tensor |
| |
| **返回值:** 产生求和结果的tensor |
| |
| --- |
| |
| #### singa.tensor.sum_rows(M) |
| |
| 按行求和。 |
| |
| **参数:** |
| - **M (Tensor)** – 输入的2维tensor |
| |
| **返回值:** 产生求和结果的tensor |
| |
| --- |
| |
| #### singa.tensor.tanh(t) |
| |
| **参数:** |
| - **t (Tensor)** – 输入tensor |
| |
| **返回值:**tensor,其中元素为 y = tanh(x),x为t中元素 |
| |
| --- |
| |
| #### singa.tensor.to_host(t) |
| |
| 将数据拷贝到host设备上。 |
| |
| --- |
| |
| #### singa.tensor.to_numpy(t) |
| |
| 拷贝tensor数据到numpy数组。 |
| |
| **参数:** |
| - **t (Tensor)** – 输入tensor |
| |
| **返回值:** numpy数组 |
| |
| --- |
| |
| #### singa.tensor.uniform(low, high, t) |
| |
| 按照均匀分布生成数值。 |
| |
| **参数:** |
| - **low (float)** – 下界 |
| - **hight (float)** – 上届 |
| - **t (Tensor)** – 结果存入t |
| |
| **返回值:** t |
| |
| --- |