Add Skeleton of Python API design #4052

reyoung · 2017-09-13T02:21:18Z

No description provided.

Superjomn · 2017-09-13T23:33:30Z

doc/design/python_api.md

@@ -0,0 +1,156 @@
+# Design Doc: Python API
+
+The top level user API in Python should be as same as API in `paddle.v2` after refactoring Paddle from a layer based framework to an operator based framework. There are many new classes in C++ in [compile time] for describing neural networks, such as `Variable`, `Operator`, `Block`. The issue about current design is how to give a proper way to wrap the C++ API to `paddle.v2` API and writing layers in Python.


writing -> write

Superjomn · 2017-09-13T23:36:07Z

doc/design/python_api.md

+
+## Python Class and compile-time protobuf
+
+Since we design our Python API concepts based on `compile-time`, we try to map our Python classes to every compile-time result, i.e., the protobuf messages. They are:


every compile-time result -> each compile-time concepts?

It is the result I want to say, not concepts. The result of compile-time is protobuf.

jacquesqiao · 2017-09-20T00:17:14Z

doc/design/python_api.md

+ self.ops.prepend(...)
+```
+
+Users are able to create a global variable inside any block since they many create parameters inside a RNN or IfElseOp. All parameters should be stored in the global block, not the step block in RNN.


inside a RNN -> inside a RNNOp

jacquesqiao · 2017-09-20T00:24:17Z

doc/design/python_api.md

+
+Users are able to create a global variable inside any block since they many create parameters inside a RNN or IfElseOp. All parameters should be stored in the global block, not the step block in RNN.
+
+Users can create local variables for outputs of operators. Users can also append and prepend an operator in current block. Prepending `random initialize` operator or `load` operator is very useful to initialize parameters before training.


Users can create local variables for outputs of operators.

what about the inputs of operators?

Inputs of operators are the other operators' output.

jacquesqiao · 2017-09-20T00:26:21Z

doc/design/python_api.md

+
+### Operator
+
+Operator class will take inputs, outputs and attributes of the operator into `protobuf` OpDesc and create a C++ `OpDesc` instance. The `infer_shape` perform on C++ objects.


take ... into OpDesc is a little strange

jacquesqiao · 2017-09-20T00:37:02Z

doc/design/python_api.md

+ block = g_block
+ w = block.create_parameter(...)
+ b = block.create_parameter(...)
+ out = stack.create_var()


what is stack for?

Actually, this is a topy, should be block

…_api_design

… into feature/python_api_design

… feature/python_api_design

helinwang · 2017-09-26T21:05:02Z

doc/design/python_api.md

+ return self.create_var(...)
+
+ def create_parameter(self, ...):
+ return self.create_global_var(...)


Does create_parameter mean create_global_var?

I guess yes, because:

All parameters should be stored in the global block

What happens if the one block's create_parameter call creates a parameter that has the same name from another block? Intuitively block A and block B creating the parameter with the same name will not interfere with each other.

Actually, no.

All parameters must be created in the global block.

All parameters are marked as Parameter. The Parameter is a subclass of Variable.

So the user can not create parameter inside a if-else block? (e.g., create a FC layer with parameter W and B).

helinwang · 2017-09-26T21:11:37Z

doc/design/python_api.md

+
+### Variable
+
+Operators' inputs, outputs, and parameters are all variables. In our design, a variable has four key attributes: its name(`name`), the block it belongs to(`block`), a pointer pointed to its C++ Protobuf object(`cpp_var_desc_ptr`), and the operator it is created by(`op`). All of these attributes are initialized in the constructor, except the `op`. The `op` will keep being `None` till the variable is taken as an operator's output.


The op will keep being None till the variable is taken as an operator's output.

Do you mean: "The value of op is None unless the variable is an operator's output."?

helinwang · 2017-09-26T21:18:50Z

doc/design/python_api.md

+
+Users are able to create a global variable inside any block since they many create parameters inside a RNN or IfElse. All parameters should be stored in the global block, not the step block in RNN.
+
+Users can create local variables for outputs of operators. Users can also append and prepend an operator in current block. Prepending `random initialize` operator or `load` operator is very useful to initialize parameters before training.


"current block" is mentioned 3 times in this document, what exactly does it mean. Is it a global variable?

Update Python API Design

reyoung and others added 10 commits September 12, 2017 19:17

Add Skeleton of Python API design

345499b

Update design

4b623c1

Update design

ea22f83

Update doc

c33a9bd

Tab to space

5f2bb1f

Update

889f5a4

Add doc for Variable

6bf1283

Add doc for Parameter

216b87a

Add doc for Layer function

709a348

Fix typo

6b222d5

Superjomn reviewed Sep 13, 2017

View reviewed changes

jacquesqiao reviewed Sep 20, 2017

View reviewed changes

reyoung and others added 5 commits September 20, 2017 10:21

Merge branch 'develop' of github.com:baidu/Paddle into feature/python…

f922479

…_api_design

Merge branch 'feature/python_api_design' of github.com:reyoung/Paddle…

f05144e

… into feature/python_api_design

Change typo

3c63b0b

Merge branch 'develop' of https://github.com/PaddlePaddle/Paddle into…

2903526

… feature/python_api_design

Add Program to Python API design doc

5314556

QiJune mentioned this pull request Sep 26, 2017

survey on computation graph #4398

Merged

helinwang reviewed Sep 26, 2017

View reviewed changes

Yi Wang and others added 2 commits September 29, 2017 20:19

Update

e6f2da4

Merge pull request #6 from wangkuiyi/python_api_yi

f6e4b3b

Update Python API Design

wangkuiyi approved these changes Sep 30, 2017

View reviewed changes

wangkuiyi merged commit f600ad1 into PaddlePaddle:develop Sep 30, 2017

reyoung deleted the feature/python_api_design branch October 2, 2017 18:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Skeleton of Python API design #4052

Add Skeleton of Python API design #4052

reyoung commented Sep 13, 2017

Superjomn Sep 13, 2017

Superjomn Sep 13, 2017

reyoung Sep 20, 2017

jacquesqiao Sep 20, 2017 •

edited

Loading

reyoung Sep 20, 2017

jacquesqiao Sep 20, 2017 •

edited

Loading

reyoung Sep 20, 2017

jacquesqiao Sep 20, 2017

jacquesqiao Sep 20, 2017

reyoung Sep 20, 2017

helinwang Sep 26, 2017

reyoung Sep 29, 2017

helinwang Sep 29, 2017

helinwang Sep 26, 2017

helinwang Sep 26, 2017

		@@ -0,0 +1,156 @@
		# Design Doc: Python API

		The top level user API in Python should be as same as API in `paddle.v2` after refactoring Paddle from a layer based framework to an operator based framework. There are many new classes in C++ in [compile time] for describing neural networks, such as `Variable`, `Operator`, `Block`. The issue about current design is how to give a proper way to wrap the C++ API to `paddle.v2` API and writing layers in Python.


		## Python Class and compile-time protobuf

		Since we design our Python API concepts based on `compile-time`, we try to map our Python classes to every compile-time result, i.e., the protobuf messages. They are:


		Users are able to create a global variable inside any block since they many create parameters inside a RNN or IfElseOp. All parameters should be stored in the global block, not the step block in RNN.

		Users can create local variables for outputs of operators. Users can also append and prepend an operator in current block. Prepending `random initialize` operator or `load` operator is very useful to initialize parameters before training.


		### Operator

		Operator class will take inputs, outputs and attributes of the operator into `protobuf` OpDesc and create a C++ `OpDesc` instance. The `infer_shape` perform on C++ objects.


		### Variable

		Operators' inputs, outputs, and parameters are all variables. In our design, a variable has four key attributes: its name(`name`), the block it belongs to(`block`), a pointer pointed to its C++ Protobuf object(`cpp_var_desc_ptr`), and the operator it is created by(`op`). All of these attributes are initialized in the constructor, except the `op`. The `op` will keep being `None` till the variable is taken as an operator's output.

Add Skeleton of Python API design #4052

Add Skeleton of Python API design #4052

Conversation

reyoung commented Sep 13, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jacquesqiao Sep 20, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jacquesqiao Sep 20, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jacquesqiao Sep 20, 2017 •

edited

Loading

jacquesqiao Sep 20, 2017 •

edited

Loading