张量(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中取样。

参数:

  • 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) – 新形状,体积和原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