From fdbc289ac38dd288fdb11f3ae18da94455625772 Mon Sep 17 00:00:00 2001
From: qiaolongfei <qiaolongfei@baidu.com>
Date: Thu, 16 Feb 2017 22:02:35 +0800
Subject: [PATCH] add v2 activation, add comment for v2 layer

---
 demo/mnist/api_train.py        |  2 +-
 python/paddle/v2/__init__.py   |  3 +-
 python/paddle/v2/activation.py | 37 +++++++++++++++++++++++
 python/paddle/v2/layer.py      | 54 ++++++++++++++++++++++++++++++++++
 4 files changed, 94 insertions(+), 2 deletions(-)
 create mode 100644 python/paddle/v2/activation.py

diff --git a/demo/mnist/api_train.py b/demo/mnist/api_train.py
index f0c56b77c..fe39f0bd2 100644
--- a/demo/mnist/api_train.py
+++ b/demo/mnist/api_train.py
@@ -77,7 +77,7 @@ def main():
     hidden2 = paddle_v2.layer.fc(input=hidden1, size=200)
     inference = paddle_v2.layer.fc(input=hidden2,
                                    size=10,
-                                   act=SoftmaxActivation())
+                                   act=paddle_v2.activation.Softmax())
     cost = paddle_v2.layer.classification_cost(input=inference, label=label)
 
     # Create Simple Gradient Machine.
diff --git a/python/paddle/v2/__init__.py b/python/paddle/v2/__init__.py
index 590fb5cd5..ec4cbb484 100644
--- a/python/paddle/v2/__init__.py
+++ b/python/paddle/v2/__init__.py
@@ -14,5 +14,6 @@
 
 import optimizer
 import layer
+import activation
 
-__all__ = ['optimizer', 'layer']
+__all__ = ['optimizer', 'layer', 'activation']
diff --git a/python/paddle/v2/activation.py b/python/paddle/v2/activation.py
new file mode 100644
index 000000000..1f3aab9ef
--- /dev/null
+++ b/python/paddle/v2/activation.py
@@ -0,0 +1,37 @@
+# Copyright (c) 2016 PaddlePaddle Authors. All Rights Reserved
+#
+# Licensed 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.
+
+from paddle.trainer_config_helpers.activations import *
+
+__all__ = [
+    "Base", "Tanh", "Sigmoid", "Softmax", "Identity", "Linear",
+    'SequenceSoftmax', "Exp", "Relu", "BRelu", "SoftRelu", "STanh", "Abs",
+    "Square", "Log"
+]
+
+Base = BaseActivation
+Tanh = TanhActivation
+Sigmoid = SigmoidActivation
+Softmax = SoftmaxActivation
+SequenceSoftmax = SequenceSoftmaxActivation
+Identity = IdentityActivation
+Linear = Identity
+Relu = ReluActivation
+BRelu = BReluActivation
+SoftRelu = SoftReluActivation
+STanh = STanhActivation
+Abs = AbsActivation
+Square = SquareActivation
+Exp = ExpActivation
+Log = LogActivation
diff --git a/python/paddle/v2/layer.py b/python/paddle/v2/layer.py
index 9c1589f9b..4acbd5ef2 100644
--- a/python/paddle/v2/layer.py
+++ b/python/paddle/v2/layer.py
@@ -11,6 +11,60 @@
 # 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.
+"""
+Before this new package paddle.v2.layer, users would need to use functions
+in paddle.trainer_config_helpers.layers to configure networks.
+
+The Old Way:
+=========
+This old way requires that the creation of a network be defined in a Python
+function, say network_config, and that this Python function being passed to
+paddle.trainer_config_helpers.parse_network_config for the creation of
+protobuf message description of this network.
+
+```python
+def network_config():
+  img = paddle.trainer_config_helpers.data_layer(name="pixel", size=784)
+  inference = paddle.trainer_config_helpers.fc_layer(
+    input=img,
+    size=10,
+    act=paddle.trainer_config_helpers.SoftmaxActivation())
+  cost = paddle.trainer_config_helpers.classification_cost(
+    input=inference,
+    label=paddle.trainer_config_helpers.data_layer(name="label", size=10))
+
+proto_desc = parse_network_config(network_config)
+```
+
+When parse_network_config executes network_config, those layer definition
+functions like data_layer and fc_layer would change some Python global variables,
+so that after the execution, parse_network_config could collect information from
+these global variables and generates the protobuf message.
+
+
+
+The New Way:
+=========
+In this PR, we define a function in paddle.v2.layer which creates a Python
+class for each layer creation function in paddle.trainer_config_helpers.layers.
+Users can use create a network as follows:
+
+```python
+img = paddle.v2.layer.data(name="pixel", size=784)
+inference = paddle.v2.layer.fc(input=img, size=10, act=paddle.v2.layer.Softmax())
+cost = paddle.v2.layer.classification(
+  input=inference,
+  label=paddle.v2.layer.data(name="label", size=10))
+
+parameters = paddle.v2.parameters.create(cost)
+```
+
+This new way doesn't require those invocations to layer definition functions
+to be in a Python function but could be anywhere.
+
+Also, the creation of a protobuf message is hidden in the invocation of
+paddle.v2.parameters.create, no longer exposed to users.
+"""
 
 import paddle.trainer_config_helpers as conf_helps
 from paddle.trainer_config_helpers.config_parser_utils import \
-- 
GitLab