name_convention.md 3.3 KB
Newer Older
1
## Operator's Parameter Name Convention
D
dongzhihong 已提交
2

D
dongzhihong 已提交
3
To make the operator document itself more clear, we recommend operator names obey the listing conventions.
D
dongzhihong 已提交
4

5
### OpProtoMaker names
D
dongzhihong 已提交
6

7
When defining an operator in Paddle, a corresponding [OpProtoMaker](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/framework/operator.h#L170) (TODO: OpProtoMaker Doc)need to be defined. All the Input/Output and Attributes will write into the [OpProto](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/framework/framework.proto#L61) , and will be used in client language to create operator. 
D
dongzhihong 已提交
8

D
dongzhihong 已提交
9
- Input/Output.
10
  - Input/Output names follow the **CamelCase**. e.g. `X`, `Y`, `Matrix`, `LastAxisInMatrix`. Input/Output much more like Variables, we prefer to meaningful English words. 
D
dongzhihong 已提交
11
  - If an operator's Input/Output are tensors in math, not match to any meaningful words, input name should starts from `X`. e.g. `X`, `Y`, and output name should starts from `Out`. e.g. `Out`. This rule intends making operators which have few inputs/outputs unified.
D
dongzhihong 已提交
12

13
- Attribute.
14
  - Attribute name follows the **snake_case**. e.g. `x`, `y`, `axis`, `rowwise_matrix`. Also, attribute name prefers to meaningful English words.
15 16

- Comments.
D
dongzhihong 已提交
17
  - Input/Output/Attr comment follow the format of **(type,default value) usage**, corresponding to which type it can be and how it will be used in the operator. e.g.  Attribute in Accumulator`"gamma" `,`(float, default 1.0) Accumulation multiplier`.
18 19 20 21
  - Operator comment format of` R"DOC(your comment here)DOC"`. You should explain the input/output of the operator first. If there is math calculation in this operator, you should write the equation in the comment. e.g. `Out = X + Y`. 

- Order.
  - Follow the order of Input/Output, then Attribute, then Comments. See the example in best practice.
D
dongzhihong 已提交
22 23

### Best Practice
D
dongzhihong 已提交
24

25 26
Here we give some examples to show how these rules will be used.

D
dongzhihong 已提交
27 28 29 30 31 32
- The operator has one input, one output. e.g.`relu`, inputs: `X`, outputs: `Out`. 

- The operator has two input, one output. e.g. `rowwise_add`, inputs : `X`, `Y`, outputs : `Out`.

- The operator contains attribute. e.g. `cosine`, inputs : `X`, `axis`, outputs : `Out`.

D
dongzhihong 已提交
33
  We give a full example of Accumulator Operator.
34 35 36 37 38 39 40

```c++
class AccumulateOpMaker : public framework::OpProtoAndCheckerMaker {
public:
  AccumulateOpMaker(framework::OpProto *proto,
                            framework::OpAttrChecker *op_checker)
    : OpProtoAndCheckerMaker(proto, op_checker) {
D
dongzhihong 已提交
41 42 43
    AddInput("X", "(Tensor) The input tensor that has to be accumulated to the output tensor. 
    If the output size is not the same as input size, 
    the output tensor is first reshaped and initialized to zero, and only then, accumulation is done.");
44
    AddOutput("Out", "(Tensor) Accumulated output tensor");
D
dongzhihong 已提交
45
    AddAttr<float>("gamma", "(float, default 1.0) Accumulation multiplier").SetDefault(1.0f);
46 47 48 49 50 51 52 53 54 55
    AddComment(R"DOC(
Accumulate operator accumulates the input tensor to the output tensor. If the
output tensor already has the right size, we add to it; otherwise, we first
initialize the output tensor to all zeros, and then do accumulation. Any
further calls to the operator, given that no one else fiddles with the output
in the interim, will do simple accumulations.
Accumulation is done as shown:

Out = 1*X + gamma*Out

D
dongzhihong 已提交
56
where X is the input tensor, Out is the output tensor and gamma is the multiplier
57 58 59 60 61
argument.
)DOC");
  }
};
```
反馈
建议
客服 返回
顶部