提交 b0b26dab 编写于 作者: A Abhinav Arora 提交者: Yi Wang

Polish operator documentation (#5356)

* Polish the documentation for uniform_random and top_k ops

* Polishing more operators
上级 7408a4c4
...@@ -163,14 +163,19 @@ class SaveOpProtoMaker : public framework::OpProtoAndCheckerMaker { ...@@ -163,14 +163,19 @@ class SaveOpProtoMaker : public framework::OpProtoAndCheckerMaker {
SaveOpProtoMaker(framework::OpProto *proto, SaveOpProtoMaker(framework::OpProto *proto,
framework::OpAttrChecker *op_checker) framework::OpAttrChecker *op_checker)
: OpProtoAndCheckerMaker(proto, op_checker) { : OpProtoAndCheckerMaker(proto, op_checker) {
AddInput("X", "The tensor need to be saved"); AddInput("X", "(Tensor ) Input tensor to be saved");
AddComment(R"DOC(Save operator AddComment(R"DOC(
Save operator will serialize and write a tensor variable to disk file. Save operator
This operator will serialize and write a tensor variable to file on disk.
)DOC"); )DOC");
AddAttr<bool>("overwrite", "Overwrite the output file if exist") AddAttr<bool>("overwrite",
"(boolean, default true)"
"Overwrite the output file if exist")
.SetDefault(true); .SetDefault(true);
AddAttr<std::string>("file_path", AddAttr<std::string>("file_path",
"Variable will be saved to \"file_path\".") "(string)"
"The \"file_path\" where the variable will be saved.")
.AddCustomChecker( .AddCustomChecker(
[](const std::string &path) { return !path.empty(); }); [](const std::string &path) { return !path.empty(); });
} }
......
...@@ -40,13 +40,16 @@ class ScaleOpMaker : public framework::OpProtoAndCheckerMaker { ...@@ -40,13 +40,16 @@ class ScaleOpMaker : public framework::OpProtoAndCheckerMaker {
public: public:
ScaleOpMaker(framework::OpProto *proto, framework::OpAttrChecker *op_checker) ScaleOpMaker(framework::OpProto *proto, framework::OpAttrChecker *op_checker)
: OpProtoAndCheckerMaker(proto, op_checker) { : OpProtoAndCheckerMaker(proto, op_checker) {
AddInput("X", "The input tensor of scale operator."); AddInput("X", "(Tensor) Input tensor of scale operator.");
AddOutput("Out", "The output tensor of scale operator."); AddOutput("Out", "(Tensor) Output tensor of scale operator.");
AddComment(R"DOC(Scale operator AddComment(R"DOC(
Scale operator
The equation is: Out = scale*X $$Out = scale*X$$
)DOC"); )DOC");
AddAttr<AttrType>("scale", "The scaling factor of the scale operator.") AddAttr<AttrType>("scale",
"(float, default 0)"
"The scaling factor of the scale operator.")
.SetDefault(1.0); .SetDefault(1.0);
} }
}; };
......
...@@ -47,19 +47,19 @@ class SequenceConcatOpMaker : public framework::OpProtoAndCheckerMaker { ...@@ -47,19 +47,19 @@ class SequenceConcatOpMaker : public framework::OpProtoAndCheckerMaker {
framework::OpAttrChecker* op_checker) framework::OpAttrChecker* op_checker)
: OpProtoAndCheckerMaker(proto, op_checker) { : OpProtoAndCheckerMaker(proto, op_checker) {
AddInput("X", AddInput("X",
"(A vector of LoDTensor), the input is a vector of LoDTensor, " "(vector<LoDTensor>) Input is a vector of LoDTensor, "
"each of which is a variable-length sequence or nested sequence.") "each of which is a variable-length sequence or nested sequence.")
.AsDuplicable(); .AsDuplicable();
AddOutput("Out", AddOutput("Out",
"(A LoDTensor), the variable-length output of " "(LoDTensor), Variable-length output of "
"sequence_concat Op."); "sequence_concat Op.");
AddAttr<int>("axis", AddAttr<int>("axis",
"(int, default 0)" "(int, default 0) "
"The axis which the inputs will be joined with. " "The axis along which the inputs will be joined. "
"If axis is 0, the inputs will be joined with LoD index.") "If axis is 0, the inputs will be joined with LoD index.")
.SetDefault(0); .SetDefault(0);
AddAttr<int>("level", AddAttr<int>("level",
"(int, default 0)" "(int, default 0) "
"The level at which the inputs will be joined. " "The level at which the inputs will be joined. "
"If the level is 0, the inputs will be joined at the nested " "If the level is 0, the inputs will be joined at the nested "
"sequence level. " "sequence level. "
...@@ -68,34 +68,36 @@ class SequenceConcatOpMaker : public framework::OpProtoAndCheckerMaker { ...@@ -68,34 +68,36 @@ class SequenceConcatOpMaker : public framework::OpProtoAndCheckerMaker {
"The level should be less than the level number of inputs.") "The level should be less than the level number of inputs.")
.SetDefault(0); .SetDefault(0);
AddComment(R"DOC( AddComment(R"DOC(
The sequence_concat operator concatenates multiple LoDTensors. Sequence Concat operator
It only supports sequence (LoD Tensor with level number is 1)
or a nested sequence (LoD tensor with level number is 2) as its input. The sequence_concat operator concatenates multiple LoDTensors.
- Case1: It only supports sequence (LoD Tensor with level number is 1)
If the axis is other than 0(here, axis is 1 and level is 1), or a nested sequence (LoD tensor with level number is 2) as its input.
each input should have the same LoD information and the LoD - Case1:
information of the output keeps the same as the input. If the axis is other than 0(here, axis is 1 and level is 1),
each input should have the same LoD information and the LoD
LoD(x0) = {{0,2,4}, {0,1,2,3,4}}; Dims(x0) = (4,3,4) information of the output keeps the same as the input.
LoD(x1) = {{0,2,4}, {0,1,2,3,4}}; Dims(x1) = (4,4,4)
LoD(Out) = {{0,2,4}, {0,1,2,3,4}}; Dims(Out) = (4,7,4) LoD(x0) = {{0,2,4}, {0,1,2,3,4}}; Dims(x0) = (4,3,4)
LoD(x1) = {{0,2,4}, {0,1,2,3,4}}; Dims(x1) = (4,4,4)
- Case2: LoD(Out) = {{0,2,4}, {0,1,2,3,4}}; Dims(Out) = (4,7,4)
If the axis is 0(here, leve is 0), the inputs are concatenated along
time steps, the LoD information of the output need to re-compute. - Case2:
If the axis is 0(here, leve is 0), the inputs are concatenated along
LoD(x0) = {{0,2,4}, {0,1,2,3,4}}; Dims(x0) = (4,3,4) time steps, the LoD information of the output need to re-compute.
LoD(x1) = {{0,3,5}, {0,1,2,3,5}}; Dims(x1) = (5,3,4)
LoD(Out) = {{0,5,9}, {0,1,2,3,4,5,6,7,9}}; Dims(Out) = (9,3,4) LoD(x0) = {{0,2,4}, {0,1,2,3,4}}; Dims(x0) = (4,3,4)
LoD(x1) = {{0,3,5}, {0,1,2,3,5}}; Dims(x1) = (5,3,4)
- Case3: LoD(Out) = {{0,5,9}, {0,1,2,3,4,5,6,7,9}}; Dims(Out) = (9,3,4)
If the axis is 0(here, level is 1).
- Case3:
LoD(x0) = {{0,2,4}, {0,1,2,3,4}}; Dims(x0) = (4,3,4) If the axis is 0(here, level is 1).
LoD(x1) = {{0,3,5}, {0,1,3,4,5}}; Dims(x1) = (5,3,4)
LoD(Out) = {{0,5,9}, {0,2,5,7,9}}; Dims(Out) = (9,3,4) LoD(x0) = {{0,2,4}, {0,1,2,3,4}}; Dims(x0) = (4,3,4)
LoD(x1) = {{0,3,5}, {0,1,3,4,5}}; Dims(x1) = (5,3,4)
NOTE: The levels of all the inputs should be the same. LoD(Out) = {{0,5,9}, {0,2,5,7,9}}; Dims(Out) = (9,3,4)
NOTE: The levels of all the inputs should be the same.
)DOC"); )DOC");
} }
}; };
......
...@@ -45,15 +45,17 @@ class SGDOpMaker : public framework::OpProtoAndCheckerMaker { ...@@ -45,15 +45,17 @@ class SGDOpMaker : public framework::OpProtoAndCheckerMaker {
public: public:
SGDOpMaker(framework::OpProto* proto, framework::OpAttrChecker* op_checker) SGDOpMaker(framework::OpProto* proto, framework::OpAttrChecker* op_checker)
: OpProtoAndCheckerMaker(proto, op_checker) { : OpProtoAndCheckerMaker(proto, op_checker) {
AddInput("Param", "Input parameter"); AddInput("Param", "(Tensor) Input parameter");
AddInput("LearningRate", "Learning rate of SGD"); AddInput("LearningRate", "(Tensor) Learning rate of SGD");
AddInput("Grad", "Input gradient"); AddInput("Grad", "(Tensor) Input gradient");
AddOutput("ParamOut", "output parameter"); AddOutput("ParamOut", "(Tensor) Output parameter");
AddComment(R"DOC( AddComment(R"DOC(
Simplest sgd algorithm. SGD operator
param_out = param - learning_rate * grad; This operator implements one step of the stochastic gradient descent algorithm.
$$param_out = param - learning_rate * grad$$
)DOC"); )DOC");
} }
......
...@@ -38,9 +38,10 @@ class SignOpMaker : public framework::OpProtoAndCheckerMaker { ...@@ -38,9 +38,10 @@ class SignOpMaker : public framework::OpProtoAndCheckerMaker {
: OpProtoAndCheckerMaker(proto, op_checker) { : OpProtoAndCheckerMaker(proto, op_checker) {
AddInput("X", "(Tensor) Input tensor of sign operator."); AddInput("X", "(Tensor) Input tensor of sign operator.");
AddOutput("Out", "(Tensor) Output tensor of sign operator."); AddOutput("Out", "(Tensor) Output tensor of sign operator.");
AddComment(R"DOC(Sign operator AddComment(R"DOC(
Sign operator
The equation is: Out = X.sign() $$Out = X.sign()$$
)DOC"); )DOC");
} }
}; };
......
...@@ -67,30 +67,38 @@ class SplitOpMaker : public framework::OpProtoAndCheckerMaker { ...@@ -67,30 +67,38 @@ class SplitOpMaker : public framework::OpProtoAndCheckerMaker {
public: public:
SplitOpMaker(framework::OpProto *proto, framework::OpAttrChecker *op_checker) SplitOpMaker(framework::OpProto *proto, framework::OpAttrChecker *op_checker)
: OpProtoAndCheckerMaker(proto, op_checker) { : OpProtoAndCheckerMaker(proto, op_checker) {
AddInput("X", "the input tensor of split operator."); AddInput("X", "(Tensor) Input tensor of the split operator.");
AddOutput("Out", "the output tensors of split operator.").AsDuplicable(); AddOutput("Out", "(Tensor) Output tensors of the split operator.")
.AsDuplicable();
AddComment(R"DOC( AddComment(R"DOC(
Split the input tensor into multiple sub-tensors. Split operator
Example:
Input = [[1,2], This operator splits the input tensor into multiple sub-tensors.
[3,4],
[5,6]] Example:
sections = [2,1] Input = [[1,2],
axis = 0 [3,4],
Output[0] = [[1,2], [5,6]]
[3,4]] sections = [2,1]
Output[1] = [[5,6]] axis = 0
Output[0] = [[1,2],
[3,4]]
Output[1] = [[5,6]]
)DOC"); )DOC");
AddAttr<std::vector<int>>("sections", AddAttr<std::vector<int>>("sections",
"the length for each" "(vector<int>) "
"output along with the specify axis.") "the length of each output along the "
"specified axis.")
.SetDefault(std::vector<int>{}); .SetDefault(std::vector<int>{});
AddAttr<int>("num", AddAttr<int>("num",
"number of the sub-tensors, it must evenly divide " "(int, default 0)"
"Number of sub-tensors. This must evenly divide "
"Input.dims()[axis]") "Input.dims()[axis]")
.SetDefault(0); .SetDefault(0);
AddAttr<int>("axis", "The axis which the input will be splited on.") AddAttr<int>("axis",
"(int, default 0) "
"The axis which the input will be splited on.")
.SetDefault(0); .SetDefault(0);
} }
}; };
......
...@@ -59,23 +59,26 @@ class SquaredL2DistanceOpMaker : public framework::OpProtoAndCheckerMaker { ...@@ -59,23 +59,26 @@ class SquaredL2DistanceOpMaker : public framework::OpProtoAndCheckerMaker {
SquaredL2DistanceOpMaker(framework::OpProto* proto, SquaredL2DistanceOpMaker(framework::OpProto* proto,
framework::OpAttrChecker* op_checker) framework::OpAttrChecker* op_checker)
: OpProtoAndCheckerMaker(proto, op_checker) { : OpProtoAndCheckerMaker(proto, op_checker) {
AddInput("X", "Input of SquaredL2DistanceOp."); AddInput("X", "(Tensor) Input of SquaredL2DistanceOp.");
AddInput("Y", "Target of SquaredL2DistanceOp."); AddInput("Y", "(Tensor) Target of SquaredL2DistanceOp.");
AddOutput("sub_result", AddOutput("sub_result",
"Buffering substraction result which " "(Tensor) Buffering subtraction result which "
"will be reused in backward.") "will be reused in backward.")
.AsIntermediate(); .AsIntermediate();
AddOutput("Out", "Squared l2 distance between input and target."); AddOutput("Out", "(Tensor) Squared l2 distance between input and target.");
AddComment(R"DOC( AddComment(R"DOC(
SquaredL2DistanceOp will cacluate the squared L2 distance for SquaredL2Distance operator
input and target. Number of distance value equals to the
first dimension of input. First dimension of target could be equal to This operator will cacluate the squared L2 distance for the input and
input or to 1. If the first dimension of target is 1, SquaredL2DistanceOp the target. Number of distance value will be equal to the first dimension
will broadcast target's first dimension to input's first dimension. of input. First dimension of the target could be equal to the input or to 1.
You can decide whether calculate the gradient of input and target. If the first dimension of target is 1, the operator will broadcast target's
first dimension to input's first dimension. During backward propagation,
Both the input X and Y can carry the LoD (Level of Details) information, the user can decide whether to calculate the gradient of the input or
or not. But the output only shares the LoD with input X. the target or both.
Both the input X and Y can carry the LoD (Level of Details) information.
However, the output only shares the LoD information with input X.
)DOC"); )DOC");
} }
}; };
......
...@@ -52,13 +52,13 @@ class SquaredL2NormOpMaker : public framework::OpProtoAndCheckerMaker { ...@@ -52,13 +52,13 @@ class SquaredL2NormOpMaker : public framework::OpProtoAndCheckerMaker {
framework::OpAttrChecker* op_checker) framework::OpAttrChecker* op_checker)
: framework::OpProtoAndCheckerMaker(proto, op_checker) { : framework::OpProtoAndCheckerMaker(proto, op_checker) {
AddInput("X", "(Tensor) The input of squared_l2_norm op."); AddInput("X", "(Tensor) The input of squared_l2_norm op.");
AddOutput("Out", "(Float) The output of squared_l2_norm op."); AddOutput("Out", "(Scalar) The output of squared_l2_norm op.");
AddComment(R"DOC( AddComment(R"DOC(
SquaredL2Norm Operator. SquaredL2Norm Operator.
Computes the squared L2 norm of a tensor. Computes the squared L2 norm of a tensor.
Out = sum (X ** 2) $$Out = \sum_{i} X_{i}^2$$
)DOC"); )DOC");
} }
......
...@@ -45,13 +45,15 @@ class SumOpMaker : public framework::OpProtoAndCheckerMaker { ...@@ -45,13 +45,15 @@ class SumOpMaker : public framework::OpProtoAndCheckerMaker {
public: public:
SumOpMaker(framework::OpProto* proto, framework::OpAttrChecker* op_checker) SumOpMaker(framework::OpProto* proto, framework::OpAttrChecker* op_checker)
: OpProtoAndCheckerMaker(proto, op_checker) { : OpProtoAndCheckerMaker(proto, op_checker) {
AddInput("X", "the input tensors of sum operator.").AsDuplicable(); AddInput("X", "(vector<Tensor>) The input tensors of sum operator.")
AddOutput("Out", "the output tensor of sum operator."); .AsDuplicable();
AddOutput("Out", "(Tensor) The output tensor of sum operator.");
AddComment(R"DOC( AddComment(R"DOC(
Sum the input tensors. Sum operator.
All the inputs can carry the LoD (Level of Details) information, This operators sums the input tensors. All the inputs can carry the
or not. But the output only shares the LoD with the first input. LoD (Level of Details) information. However, the output only shares
the LoD information with the first input.
)DOC"); )DOC");
} }
}; };
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册