Design Of Refactor Topology

doc/design/layer_generation/00.how_to_write_a_layer.md

@@ -0,0 +1,159 @@
+# 如何写一个Layer
+
+这个文档是一个概念性的文档，描述在重构后用户如何写一个Layer。
+
+## 基本目标
+
+用户只需要写Layer的计算信息，而不需要写配置解析器，也不修改写Protobuf的内容。就可以完成Layer的书写。
+
+## 实现方式
+
+### 总体概览
+
+* 在注册Layer的时候，不只注册Layer的C++类型，同时注册Layer的信息，这个信息使用Protobuf来表示。
+* 使用一个静态函数生成，Layer信息的Protobuf。
+
+
+### LayerDef/LayerOutputDef Protobuf.
+
+Paddle将Layer在C++端注册信息，声明成Protobuf。一个Layer的信息主体分为两个部分:
+
+* Layer本身的信息
+	* 包括这个Layer支持什么样类型的输入
+	* 这个Layer的参数，bias有哪些可以设置的属性
+	* 这个Layer本身有哪些可以设置的属性
+* Layer输出什么类型
+	* 这个Layer在某一种输入下，的输出类型是什么样子的。
+	* 由于Paddle的一个Layer可以接受和产生不同类型的输入和输出，Layer的输出类型(例如size)是和输入有关系的。所以这个信息是解析配置文件过程中运行时调用生成的。
+
+```protobuf
+enum DataType {
+  DENSE=0,
+  SPARSE_INT=1,
+  SPARSE=2,
+  INT=3,
+}
+
+enum AttributeType {
+  STRING=0,
+  INT=1,
+  FLOAT=2,
+  DOUBLE=3,
+  ...
+}
+
+message Attribute {
+  oneof {
+    string s_value = 1;
+    int    i_value = 2;
+    float  f_value = 3;
+    ...
+  }
+}
+
+message AttributeDef {
+  required string name = 1;  // supported attribute name.
+  required AttributeType type = 2;  // supported type.
+  required string description = 3; // Attribute description & comments.
+
+  optional Attribute default_value = 4; // default value.
+  optional Attribute max_value = 5;    // max value.
+  optional Attribute min_value = 6;   // min value.
+}
+
+// Argument Define the Supported InputTypes.
+message ArgumentDef {
+   	// Supported Input Type.
+   	// The data type of input/output.
+   	repeated DataType data_type = 1; 
+   	// 0 means it is not a sequence. 1 means a plain sequence. 2 means a nested sequence.  One layer could support many sequence type.
+   	repeated uint32 seq_nested_level = 2;
+
+   	// In paddle, some layer can handle variable length input.
+   	// If some input is repeatable, it means there are one or many inputs as the same input type.
+   	required bool repeatable = 3;
+
+	// In Paddle, a layer could return many outputs. Each output contains a different name.
+   	required string name = 4;
+
+   	// Comments
+  	required string description = 5;
+}
+
+message LayerDef {
+    required string type = 1;  // Layer type, such as 'fc', 'conv'
+    required string description = 2;  // Layer description & comments.
+
+
+    repeated ArgumentDef inputs = 3;
+
+
+    message ParameterDef {
+        repeated AttributeDef attributes = 1;  // Parameter Attributes Definition.
+    }
+
+    // Each input of Paddle Layer should contain zero or one parameter.
+    // so parameter_attr.size() == inputs.size()
+    repeated ParameterDef parameter_attr = 5;
+
+    // Set the bias attribute, If this layer support bias.
+    optional ParameterDef bias_attr = 6;
+
+    // The Layer Attributes.
+    repeated AttributeDef layer_attr = 7;
+}
+
+// Define the layer's output types by given input types.
+message LayerOutputDef {
+	// Output name, Each Paddle Layer could have multiple outputs.
+	optional string name = 1;
+
+	// Output type
+	required DataType type = 2;
+	required uint32 size = 3;
+	required uint32 seq_nested_level = 4;
+
+}
+```
+
+### C++ 端暴露LayerDef/LayerOutputDef Protobuf.
+
+基本想法:
+
+* 对于每一种类型的Layer，Paddle根据Layer的名字约定两个全局函数的名字。例如，对于FC Layer，全局函数的名字是 `__get_fc_layer_definition__` 和 `__get_fc_layer_output_definition__`。 这两个全局函数通过`REGISTER_LAYER`自动生成。
+* 对于每个Layer实现的时候，实现两个静态(`static`)函数，分别实现这两个函数。
+
+举例来说，例如对于FCLayer，可能的实现为:
+
+```C++
+
+class FCLayer :public Layer {
+public:
+  void init() { ... }
+  void forward() { ... }
+  void backward() { ... }
+
+  static void getLayerDefinition(LayerDef& def) {
+    LayerDefinition::supportSize(def);
+    LayerDefinition::supportDropout(def);
+    LayerDefinition::addInput()
+        .setRepeatable(True)
+        .addSupport({ InputType::Dense, InputType::SparseInt, InputType::Sparse })
+        .addSupportSeqLevel({0, 1, 2})
+        .addDoc("FC Layer is fully connected. Blah blah blah...");
+  }
+
+  static std::vector<LayerOutputDef> getLayerOutputDefinition(const std::vector<LayerOutputDef>& inputs,
+  	    LayerConfig& self) {
+  	 // self could be modified, for calculating parameter size, etc.
+    LayerOutputDef out;
+    out.set_size(self.size());
+    out.set_type(InputType::Dense);
+    out.set_seq_nested_level(inputs[0].seq_nested_level);
+    return { out };
+  }
+};
+
+
+REGISTER_LAYER(fc, FCLayer);
+```

doc/design/layer_generation/01.use_map_in_protobuf.md

@@ -0,0 +1,62 @@
+# 在Protobuf中支持多种类型的字典字段
+
+## 背景
+
+这项工作的背景是我们要使用代码生成器或者运行时自动生成模型配置函数，并在运行时自动检查配置的正确性。
+
+
+现阶段如何编写一个Layer呢？可以参考[文章](http://www.paddlepaddle.org/doc/dev/new_layer/index.html)。主体可以分为以下几个步骤:
+
+* 在[Protobuf文件](https://github.com/PaddlePaddle/Paddle/blob/develop/proto/ModelConfig.proto#L284)里，添加里面编写这个Layer需要的参数。如果这个Layer只需要size等常见配置，这个protobuf已经包含，复用即可。但是如果这个Layer有其他自定义的参数，就需要在这个文件里面添加字段。
+	* 也就是目前新建Layer和修改Protobuf文件是强耦合的。且这个protobuf message已经有了52个字段了。
+* 在C++端实现Layer
+* 在Python端实现这个Layer的解析函数，Wrapper，V2Layer等等。
+
+
+这个设计文档，旨在解决 Protobuf文件和Layer之间的耦合性，让用户新建一个Layer的时候不需要改Protobuf。并且，极大的简化Protobuf文件。
+
+## 实现方式
+
+使用Protobuf中的[map](https://developers.google.com/protocol-buffers/docs/proto#maps)和[oneof](https://developers.google.com/protocol-buffers/docs/proto#oneof)将Paddle Potobuf中的配置简化成一个`map<string, variant>`形式。
+
+简单的示例代码为:
+
+```protobuf
+message Attribute {
+    oneof AttributeField {
+   	     string s_value = 1;
+   	     int    i_value = 2;
+   	     float  f_value = 3;
+   	     double d_value = 4;
+   	     ...
+    }
+}
+
+message LayerConfig {
+   required string name = 1;
+   required string type = 2;
+   map<string, Attribute> attributes = 3;
+}
+```
+
+其中，每种Layer都有不同的`type`。 而`attributes`作为一个`map`，他的Key可以被每个Layer自己定义。对于一些常见的配置参数，例如`activation`，可以共享一个key。对于一些layer专有属性，可以使用`.`分隔开。例如，对于CTCLayer可以设置`blank`属性，它的Key可以为`ctc.blank`。
+
+这样，实现一个新的Layer，用户就不需要修改Protobuf消息了。并且，用户写一个新的Layer的时候，可以说明自己需要哪些属性，而这些属性的取值范围又是如何的。这样，我们在生成Python配置函数的代码时，可以生成运行时检查的代码。避免用户错误的配置神经网络。
+
+
+## 实现问题
+
+实现这项工作目前来看有如下几个先决条件需要解决:
+
+* 这项工作会修改 `Python <==> Paddle core`中间的protobuf消息定义，对于Python端Layer解析函数，需要有覆盖完整的单元测试，才能保证这一步工作进行完之后，系统行为没有问题。否则，直接修改 Protobuf 风险较高。
+* `oneof`与`map`是`protobuf2`语法，但是这是在`Protobuf 3.0`之后的代码库中添加的功能，如果Paddle依赖这个功能，那么Paddle必须依赖Protobuf 3.0以上的Protobuf版本。
+
+
+## 总结
+
+* 最终目的: 用户只需要写Layer的C++实现，剩下的Python代码自动生成
+* 阶段目的: 解耦合 Protobuf与Layer的C++实现
+* 解决办法: 用`map`和`oneof`，将属性变成一个多种类型的字典
+* 问题:
+	* 需要先完善config_parser的单测，增加单测覆盖率
+	* 这会让Paddle强制依赖`Protobuf 3.0+`的Protobuf