张量(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
用法示例：
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) – 一个列表的整形数据作为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中取样。
参数：
clone()
返回值： 一个新Tensor，是待拷贝Tensor的深拷贝
copy()
调用singa::Tensor的拷贝构造器进行浅拷贝。
copy_data(t)
从另一个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()
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形状，数据类型和设备。
参数：
set_value(x)
设置所有元素值为给定值。
参数：
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)
参数：
返回值： 一个新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)
参数：
返回值： 新tensor，其中元素为 y = exp(x)，x为t中元素
singa.tensor.from_numpy(np_array)
根据numpy数组的形状、数据类型和数值创建一个tensor。
参数：
返回值： 分配在默认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)
参数：
返回值： 一个新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)
参数：
返回值： tensor，其中元素为 y = x 若x >0；否则y = 0，x为t中元素
singa.tensor.reshape(t, s)
改变tensor的形状。
参数：
- t (Tensor) – 待改变形状的tensor
- s (list) – 新形状，体积和原tensor体积相同
返回值： 新tensor
singa.tensor.sigmoid(t)
参数：
返回值： tensor，其中元素为 y = sigmoid(x)，x为t中元素
singa.tensor.sign(t)
参数：
返回值： 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)
参数：
返回值： tensor，其中元素为 y = sqrt(x)，x为t中元素
singa.tensor.square(t)
参数：
返回值： 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)
按列求和。
参数：
返回值： 产生求和结果的tensor
singa.tensor.sum_rows(M)
按行求和。
参数：
返回值： 产生求和结果的tensor
singa.tensor.tanh(t)
参数：
**返回值：**tensor，其中元素为 y = tanh(x)，x为t中元素
singa.tensor.to_host(t)
将数据拷贝到host设备上。
singa.tensor.to_numpy(t)
拷贝tensor数据到numpy数组。
参数：
返回值： numpy数组
singa.tensor.uniform(low, high, t)
按照均匀分布生成数值。
参数：
- low (float) – 下界
- hight (float) – 上届
- t (Tensor) – 结果存入t
返回值： t