层(Layer)

Python API

Python层将C++层封装成更简单的API。

示例用法：

from singa import layer
from singa import tensor
from singa import device

layer.engine = 'cudnn'  # to use cudnn layers
dev = device.create_cuda_gpu()

# create a convolution layer
conv = layer.Conv2D('conv', 32, 3, 1, pad=1, input_sample_shape=(3, 32, 32))
conv.to_device(dev)  # move the layer data onto a CudaGPU device
x = tensor.Tensor((3, 32, 32), dev)
x.uniform(-1, 1)
y = conv.foward(True, x)

dy = tensor.Tensor()
dy.reset_like(y)
dy.set_value(0.1)
# dp is a list of tensors for parameter gradients
dx, dp = conv.backward(kTrain, dy)

singa.layer.engine = ‘cudnn’

引擎（engine）是层标识符的前缀。这个值可能是[cudnn'，‘singacpp’，‘singacuda’，‘singacl’]之一，分别用cudnn库，Cpp，Cuda和OpenCL实现。例如，CudnnConvolution层由‘cudnn_convolution’标识; ‘singacpp_convolution’用于卷积层; 有些层的实现只使用tensor函数，因此它们对底层设备是透明的。对于这些层，它们将具有多个标识符，例如，singacpp_dropout，singacuda_dropout和singacl_dropout全都用于Dropout层。此外，它还有一个额外的标识符‘singa’，即‘singa_dropout’也代表Dropout层。

引擎是大小写敏感的。每个python层将会用引擎属性创建正确的层。

class singa.layer.Layer(name, conf=None, **kwargs)

基类：object

Python层的基类。典型地，层实例的生命周期包括：

构造层没有input_sample_shapes，转到2;用input_sample_shapes构建层，转到3
调用setup来创建参数并设置其他元字段
调用前向传播或访问层成员
调用后向传播并获取参数完成更新

参数：

name (str) – 层名

setup(in_shapes)

调用C++setup函数创建参数并设置元数据。

参数：

in_shapes – 如果层接受单个输入tensor，则in_shapes是指定输入tensor形状的单个元组; 如果该层接受多个输入tensor（例如，concatenation层），则in_shapes是元组的元组，每个元组对于一个输入tensor

caffe_layer()

基于caffe层的配置创建一个SINGA层

get_output_sample_shape()

在setup以获得输出样本的形状后被调用

返回值： 单个输出tensor的元组；如果该层具有多个输出，则为元组列表

param_names()

返回值： 字符串列表，每个值代表一个参数tensor的名称

param_values()

返回参数值tensor。参数tesnor不作为层成员存储。由于层设备的更改，cpp tensor可能会移动到diff设备上，这会导致不一致。

返回值： tensor列表，每个参数对应列表中的一个

forward(flag, x)

当前层的前向传播。

参数：

flag – True (kTrain) for training (kEval); False for evaluating; other values for furture use.
x (Tensor or list) – an input tensor if the layer is connected from a single layer; a list of tensors if the layer is connected from multiple layers.

返回值： 如果该层被连接在一个单独的层则返回tensor；如果被连接到多个层，则返回一个tensor列表

backward(flag, dy)

当前层的后向传播。

参数：

flag (int) – 保留为以后使用
dy (Tensor or list) – 与目标损失相对应的梯度tensor

返回值： <dx, <dp1, dp2..>>，dx是输入x的梯度，dpi是第i个参数的梯度

to_device(device)

将层状态tensor移至指定设备。

参数：

device – swig转换的设备，由singa.device创建

class singa.layer.Dummy(name, input_sample_shape=None)

基类：singa.layer.Layer

一个虚拟层，仅用于向前/向后传递数据（输入/输出是单个tensor）。

forward(flag, x)

返回值： 输入x

backward(falg, dy)

返回值： dy，[]

class singa.layer.Conv2D(name, nb_kernels, kernel=3, stride=1, border_mode=‘same’, cudnn_prefer=‘fatest’, data_format=‘NCHW’, use_bias=True, W_specs=None, b_specs=None, pad=None, input_sample_shape=None)

基类：singa.layer.Layer

创建一个层做2D卷积。

参数：

nb_kernels (int) – 输入tensor的通道（核）数
kernel – 一个或一对整型数表示核的高和宽
stride – 一个或一对整型数表示步长的高和宽
border_mode (string) – 填充模式，不区分大小写，‘valid’ -> 在高和宽长度上补0 ‘same’ -> 填充核一半（下取整）数目的0，核必须是奇数
cudnn_prefer (string) – 偏好的cudnn卷积算法，可以是‘fatest’, ‘autotune’, ‘limited_workspace’和‘no_workspace’
data_format (string) – ‘NCHW’或‘NHWC’
use_bias (bool) – True或False
pad – 一个或一对整型数表示填充的高和宽
W_specs (dict) – 用于指定权重矩阵的规格，字段包括代表参数名称的‘name’，代表学习速率乘数的‘lr_mult，代表权重衰减乘数的’‘decay_mult’，代表初始化方法的‘init’，其可以是‘gaussian’，‘uniform’，' xavier'，相应的初始化方法为‘‘‘std’，‘mean’，‘high’，‘low’。TODO（wangwei）‘clamp’为渐变约束，value为标量，‘regularizer’为正规化，目前支持’l2’
b_specs (dict) – 偏移向量的超参数，同W_specs类似
name (string) – 层名
input_sample_shape – 用于输入tensor形状的三元组，例如（通道，高度，宽度）或（高度，宽度，通道）

class singa.layer.Conv1D(name, nb_kernels, kernel=3, stride=1, border_mode=‘same’, cudnn_prefer=‘fatest’, use_bias=True, W_specs={‘init’: ‘Xavier’}, b_specs={‘init’: ‘Constant’, ‘value’: 0}, pad=None, input_sample_shape=None)

基类：singa.layer.Conv2D

构建1D卷积层。大部分参数与Conv2D的参数相同，除了核，步长，填充值，这是一个标量而不是元组。 input_sample_shape是一个具有单个输入特征长度值的元组。

get_output_sample_shape()

class singa.layer.Pooling2D(name, mode, kernel=3, stride=2, border_mode=‘same’, pad=None, data_format=‘NCHW’, input_sample_shape=None)

基类：singa.layer.Layer

2D池化层进行最大或平均池化。所有的参数都与Conv2D相同，除了下面的参数。

参数：

mode – 池化模式，model_pb2.PoolingConf.MAX或model_pb2.PoolingConf.AVE

class singa.layer.MaxPooling2D(name, kernel=3, stride=2, border_mode=‘same’, pad=None, data_format=‘NCHW’, input_sample_shape=None)

基类: singa.layer.Pooling2D

class singa.layer.AvgPooling2D(name, kernel=3, stride=2, border_mode=‘same’, pad=None, data_format=‘NCHW’, input_sample_shape=None)

基类: singa.layer.Pooling2D

class singa.layer.MaxPooling1D(name, kernel=3, stride=2, border_mode=‘same’, pad=None, data_format=‘NCHW’, input_sample_shape=None)

基类: singa.layer.MaxPooling2D

get_output_sample_shape()

class singa.layer.AvgPooling1D(name, kernel=3, stride=2, border_mode=‘same’, pad=None, data_format=‘NCHW’, input_sample_shape=None)

基类: singa.layer.AvgPooling2D

get_output_sample_shape()

class singa.layer.BatchNormalization(name, momentum=0.9, beta_specs=None, gamma_specs=None, input_sample_shape=None)

基类：singa.layer.Layer

批量正则化。

参数：

momentum (float) – 用于运行的均值和方差
beta_specs (dict) – 字典，包括beta参数的字段：‘name’参数名称'；lr_mult‘学习速率乘数；‘decay_mult’权重衰减乘数；‘init’初始化方法；可以是’gaussian'，‘uniform’和‘xavier’，‘std’，‘mean’，‘high’，‘low’表示相应初始化方法；‘clamp’表示梯度约束，值是标量；‘regularizer’用于正则化，目前支持‘l2’
gamma_specs (dict) – 同beta_specs类似, 但用于gamma参数.
name (string) – 层名
input_sample_shape (tuple) – 整型数，至少一个

class singa.layer.LRN(name, size=5, alpha=1, beta=0.75, mode=‘cross_channel’, k=1, input_sample_shape=None)

基类：singa.layer.Layer

局部响应归一化。

参数：

size (int) – 用于归一化的通道数.
mode (string) – ‘cross_channel’
input_sample_shape (tuple) – 3维元组，(channel, height, width)

class singa.layer.Dense(name, num_output, use_bias=True, W_specs=None, b_specs=None, W_transpose=False, input_sample_shape=None)

基类：singa.layer.Layer

进行线性或放射变换，也被叫做内积或全连接层。

参数：

num_output (int) – 输出特征长度
use_bias (bool) – 转换后的特征向量是否加上偏移向量
W_specs (dict) – 包含权值矩阵的字段：‘name’参数名称'；lr_mult‘学习速率乘数；‘decay_mult’权重衰减乘数；‘init’初始化方法；可以是’gaussian'，‘uniform’和‘xavier’，‘std’，‘mean’，‘high’，‘low’表示相应初始化方法；‘clamp’表示梯度约束，值是标量；‘regularizer’用于正则化，目前支持‘l2’
b_specs (dict) – 偏移向量的字段, 同W_specs类似
W_transpose (bool) – 如果为真，输出为x*W.T+b
input_sample_shape (tuple) – 输入特征长度

class singa.layer.Dropout(name, p=0.5, input_sample_shape=None)

基类：singa.layer.Layer

Dropout层

参数：

p (float) – 随机丢掉一个元素（即将其中设为0）的概率
name (string) – 层名

class singa.layer.Activation(name, mode=‘relu’, input_sample_shape=None)

基类：singa.layer.Layer

激励层

参数：

name (string) – 层名
mode (string) – ‘relu’, ‘sigmoid’或 ‘tanh’
input_sample_shape (tuple) – 单个样本的形状

class singa.layer.Softmax(name, axis=1, input_sample_shape=None)

基类：singa.layer.Layer

采用SoftMax。

参数：

axis (int) – 对[axis, -1)的数据逐个进行SoftMax
input_sample_shape (tuple) – 单个样本的形状

class singa.layer.Flatten(name, axis=1, input_sample_shape=None)

基类：singa.layer.Layer

将输入tensor重塑为一个矩阵。

参数：

axis (int) – 根据指定维度将输入重塑为矩阵，[0,axis)作为行，[axis, -1)作为列
input_sample_shape (tuple) – 单个样本的形状

class singa.layer.Merge(name, input_sample_shape=None)

基类：singa.layer.Layer

对所有输入tensor求和。

参数：

input_sample_shape – 输入样本的形状。所有样本的形状应该一致。

setup(in_shape)

get_output_sample_shape()

forward(flag, inputs)

通过求和合并所有输入tensor。 TODO(wangwei) 元素级别的合并操作。

返回值： 单个tensor，包含所有输入tensor的和

backward(flag, grad)

复制每个输入层的梯度tensor。

参数：

grad - 梯度tensor

返回值： tensor列表，每个输入层对应其中一个

class singa.layer.Split(name, num_output, input_sample_shape=None)

基类：singa.layer.Layer

生成输入tensor的多个副本。

参数：

num_output (int) – 待生成的输出tensor数目
input_sample_shape() – 包含一个整型数，代表输入样本特征大小

setup(in_shape)

get_output_sample_shape()

forward()

生成输入tensor的多个副本。

参数：

flag – 没有用到
input – 单个输入tensor

返回值： 输出tensor列表，每个对应输入的一个拷贝

backward()

对所有输入tensor求和得到单个输出tensor。

参数：

grad - 梯度tensor

返回值： 一个tensor，代表所有输入梯度tensor的求和

class singa.layer.Concat(name, axis, input_sample_shapes=None)

基类：singa.layer.Layer

将tensor竖直(axis=0)或水平(axis=1)拼接。目前仅支持2维tensor。

参数：

axis (int) – 0表示拼接行; 1表示拼接列;
input_sample_shapes – 样本形状的元组列表，每个对应一个输入样本的tensor

forward(flag, inputs)

拼接所有输入tensor。

参数：

flag – 同Layer::forward()
input – tensor列表

返回值： 一个拼接后的tensor

backward(flag, dy)

参数：

flag – same as Layer::backward()
dy (Tensor) – the gradient tensors of y w.r.t objective loss

返回值： 元组(dx, []), dx是tensor列表，对应输入的梯度；[]是空列表

class singa.layer.Slice(name, axis, slice_point, input_sample_shape=None)

基类：singa.layer.Layer

将输入tensor沿竖直(axis=0)或水平(axis=1)分成多个子tensor。

参数：

axis (int) – 0代表分割行; 1代表分割列;
slice_point (list) – 沿着轴分割的位置；n-1个分割点对应n个子tensor；
input_sample_shape – 输入样本tensor的形状

get_output_sample_shape()

forward(flag, x)

沿给定轴分割输入tensor。

参数：

flag – 同Layer::forward()
x – 单个输入tensor

返回值： 输出tensor列表

backward(flag, grads)

拼接所有梯度tensor以生成一个输出tensor。

参数：

flag – 同Layer::backward()
grads – tensor列表，每个对应一个分割的梯度tensor 返回值： 元组(dx, []), dx是一个tensor，对应原始输入的梯度；[]是空列表

class singa.layer.RNN(name, hidden_size, rnn_mode=‘lstm’, dropout=0.0, num_stacks=1, input_mode=‘linear’, bidirectional=False, param_specs=None, input_sample_shape=None)

基类：singa.layer.Layer

递归层包含4个单元，即lstm, gru, tanh和relu。

参数：

hidden_size – 隐含层特征大小，同所有层的堆栈。
rnn_mode – 决定了RNN单元，可以是‘lstm’, ‘gru’, ‘tanh’和 ‘relu’。对于每种模式，可以参考cudnn手册。
num_stacks – rnn层的堆栈数量。这不同于需要展开的序列长度。
input_mode – ‘linear’，通过线性变换将输入特征x转换成大小为hidden_size的特征向量；‘skip’，仅要求输入特征大小等于hidden_size。
bidirection – 对于双向RNN为真。
param_specs – RNN参数的初始化配置。
input_sample_shape – 包含一个整型数，代表输入样本的特征大小。

forward(flag, inputs)

参数：

flag – True(kTrain) 代表训练；False(kEval)代表验证; 其他值用作以后使用。
<x1, x2,..xn, hx, cx> – 其中，xi是输入(inputs,)第i个位置的tensor，它的形状是 (batch_size, input_feature_length); xi的batch_size必须大于xi + 1的大小; hx是初始隐藏状态，形状是（num_stacks * bidirection？2：1，batch_size，hidden_size）。 cx是与hy相同形状的初始细胞状态张量。 cx仅对lstm有效。对于其他RNN，不存在cx。 hx和cx都可以是没有形状和数据的虚拟张量。返回值：<y1，y2，... yn，hy，cy>，其中yi是第i个位置的输出张量，其形状是（batch_size，hidden_size *双向？2：1）。 hy是最终的隐藏状态张量。 cx是最终的细胞状态张量。 cx仅用于lstm。

backward(flag, grad)

参数：

flag – 未来使用
<dy1, dy2,..dyn, dhy, dcy> - 其中，dyi是(grad,) 第i个位置的梯度，它的形状是 (batch_size, hidden_size*bidirection?2 (i-th) – 1); dhy是最终隐藏状态的渐变，它的形状是（num_stacks *双向？2：1，batch_size，hidden_size）。dcy是最终单元状态的梯度。 cx仅对lstm有效，其他RNN不存在cx。 dhy和dcy都可以是没有形状和数据的虚拟tensor。

返回值： <dx1，dx2，... dxn，dhx，dcx>，其中dxi是第i个输入的梯度张量，它的形状是（batch_size，input_feature_length）。 dhx是初始隐藏状态的梯度。 dcx是初始单元状态的梯度，仅对lstm有效。

class singa.layer.LSTM(name, hidden_size, dropout=0.0, num_stacks=1, input_mode=‘linear’, bidirectional=False, param_specs=None, input_sample_shape=None)

基类：singa.layer.RNN

class singa.layer.GRU(name, hidden_size, dropout=0.0, num_stacks=1, input_mode=‘linear’, bidirectional=False, param_specs=None, input_sample_shape=None)

基类：singa.layer.RNN

singa.layer.get_layer_list()

返回包含所有支持图层的标识符（标签）的字符串列表