<!--
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.
-->
# 层(Layer)

## Python API

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

示例用法：

```python
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层的基类。
典型地，层实例的生命周期包括：

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

**参数：**
- **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<Tensor>)** – 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>)** – 与目标损失相对应的梯度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()

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

---