From c1bb602e6b837af1e511525f930893fadd7e0696 Mon Sep 17 00:00:00 2001
From: Yi Wang <yiwang01@baidu.com>
Date: Wed, 20 Sep 2017 12:12:27 -0700
Subject: [PATCH] Add program.md

---
 doc/design/program.md | 59 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 doc/design/program.md

diff --git a/doc/design/program.md b/doc/design/program.md
new file mode 100644
index 00000000000..cc1ffcbaf93
--- /dev/null
+++ b/doc/design/program.md
@@ -0,0 +1,59 @@
+# Design Doc: ProgramDesc
+
+The basic structure of a PaddlePaddle program is some nested blocks, as a C++ or Java program.
+
+As described in [graph.md](./graph.md), the first five lines of the following PaddlePaddle program
+
+```python
+x = layer.data("images")
+l = layer.data("label")
+y = layer.fc(x)
+cost = layer.mse(y, l)
+optimize(cost)
+train(cost, reader=mnist.train())
+```
+
+generates, or compiles, a PaddelPaddle program, which is represented by the following protobuf message:
+
+```protobuf
+message ProgramDesc {
+  repeated BlockDesc blocks = 1;
+}
+
+message BlockDesc {
+  repeated VarDesc vars = 1;
+  repeated OpDesc ops = 2;
+}
+
+message OpDesc {
+  AttrDesc attrs = 1;
+  ...
+}
+
+message AttrDesc {
+  required AttrType type = 1;
+
+  // index into ProgramDesc::blocks when type==BLOCK
+  optional int32 block = 2;
+  ...
+}
+```
+
+When each of the first five lines runs, related Python function, e.g., `layer.fc`, calls C++ InferShape functions.  This InferShape function needs to access the properties of VarDesc's accessed by the current OpDesc. These VarDesc's might not be defined in the current block, but in some ancestor blocks.  This requires that we can trace the parent of a block.
+
+A nested block is often an attribute of an operator, most likely, an IfElseOp or a WhileOp.  In above solution, all blocks are in `ProgramDesc::blocks`, this implicitly assigns a zero-based ID to each block -- the index of the block in `ProgramDesc::blocks`.  So that `AttrDesc::block` could be an integer block ID.
+
+With this design, the InferShape function should take the following parameters:
+
+```c++
+void InferShape(const ProgramDesc* program,
+                int current_block,
+                int current_operator) {
+  ...
+}
+```
+
+where
+
+- `current_block` indices into `ProgramDesc::blocks`,
+- `current_operator` indices into `BlockDesc::ops`.
-- 
GitLab