From b0b26dabe7759fbc1ba8e627e6b66863bbfff81b Mon Sep 17 00:00:00 2001 From: Abhinav Arora Date: Fri, 3 Nov 2017 14:21:23 -0700 Subject: [PATCH] Polish operator documentation (#5356) * Polish the documentation for uniform_random and top_k ops * Polishing more operators --- paddle/operators/save_op.cc | 15 +++-- paddle/operators/scale_op.cc | 13 +++-- paddle/operators/sequence_concat_op.cc | 68 +++++++++++----------- paddle/operators/sgd_op.cc | 14 +++-- paddle/operators/sign_op.cc | 5 +- paddle/operators/split_op.cc | 40 ++++++++----- paddle/operators/squared_l2_distance_op.cc | 29 ++++----- paddle/operators/squared_l2_norm_op.cc | 4 +- paddle/operators/sum_op.cc | 12 ++-- 9 files changed, 113 insertions(+), 87 deletions(-) diff --git a/paddle/operators/save_op.cc b/paddle/operators/save_op.cc index 490256dfa1c..56909fb65f4 100644 --- a/paddle/operators/save_op.cc +++ b/paddle/operators/save_op.cc @@ -163,14 +163,19 @@ class SaveOpProtoMaker : public framework::OpProtoAndCheckerMaker { SaveOpProtoMaker(framework::OpProto *proto, framework::OpAttrChecker *op_checker) : OpProtoAndCheckerMaker(proto, op_checker) { - AddInput("X", "The tensor need to be saved"); - AddComment(R"DOC(Save operator -Save operator will serialize and write a tensor variable to disk file. + AddInput("X", "(Tensor ) Input tensor to be saved"); + AddComment(R"DOC( +Save operator + +This operator will serialize and write a tensor variable to file on disk. )DOC"); - AddAttr("overwrite", "Overwrite the output file if exist") + AddAttr("overwrite", + "(boolean, default true)" + "Overwrite the output file if exist") .SetDefault(true); AddAttr("file_path", - "Variable will be saved to \"file_path\".") + "(string)" + "The \"file_path\" where the variable will be saved.") .AddCustomChecker( [](const std::string &path) { return !path.empty(); }); } diff --git a/paddle/operators/scale_op.cc b/paddle/operators/scale_op.cc index 5fcacf70d80..5745580504f 100644 --- a/paddle/operators/scale_op.cc +++ b/paddle/operators/scale_op.cc @@ -40,13 +40,16 @@ class ScaleOpMaker : public framework::OpProtoAndCheckerMaker { public: ScaleOpMaker(framework::OpProto *proto, framework::OpAttrChecker *op_checker) : OpProtoAndCheckerMaker(proto, op_checker) { - AddInput("X", "The input tensor of scale operator."); - AddOutput("Out", "The output tensor of scale operator."); - AddComment(R"DOC(Scale operator + AddInput("X", "(Tensor) Input tensor of scale operator."); + AddOutput("Out", "(Tensor) Output tensor of scale operator."); + AddComment(R"DOC( +Scale operator -The equation is: Out = scale*X +$$Out = scale*X$$ )DOC"); - AddAttr("scale", "The scaling factor of the scale operator.") + AddAttr("scale", + "(float, default 0)" + "The scaling factor of the scale operator.") .SetDefault(1.0); } }; diff --git a/paddle/operators/sequence_concat_op.cc b/paddle/operators/sequence_concat_op.cc index 46f73e3c279..ec4ad50dab7 100644 --- a/paddle/operators/sequence_concat_op.cc +++ b/paddle/operators/sequence_concat_op.cc @@ -47,19 +47,19 @@ class SequenceConcatOpMaker : public framework::OpProtoAndCheckerMaker { framework::OpAttrChecker* op_checker) : OpProtoAndCheckerMaker(proto, op_checker) { AddInput("X", - "(A vector of LoDTensor), the input is a vector of LoDTensor, " + "(vector) Input is a vector of LoDTensor, " "each of which is a variable-length sequence or nested sequence.") .AsDuplicable(); AddOutput("Out", - "(A LoDTensor), the variable-length output of " + "(LoDTensor), Variable-length output of " "sequence_concat Op."); AddAttr("axis", - "(int, default 0)" - "The axis which the inputs will be joined with. " + "(int, default 0) " + "The axis along which the inputs will be joined. " "If axis is 0, the inputs will be joined with LoD index.") .SetDefault(0); AddAttr("level", - "(int, default 0)" + "(int, default 0) " "The level at which the inputs will be joined. " "If the level is 0, the inputs will be joined at the nested " "sequence level. " @@ -68,34 +68,36 @@ class SequenceConcatOpMaker : public framework::OpProtoAndCheckerMaker { "The level should be less than the level number of inputs.") .SetDefault(0); AddComment(R"DOC( - The sequence_concat operator concatenates multiple LoDTensors. - 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. - - Case1: - 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 - information of the output keeps the same as the input. - - 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) - LoD(Out) = {{0,2,4}, {0,1,2,3,4}}; Dims(Out) = (4,7,4) - - - Case2: - 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. - - 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) - LoD(Out) = {{0,5,9}, {0,1,2,3,4,5,6,7,9}}; Dims(Out) = (9,3,4) - - - Case3: - If the axis is 0(here, level is 1). - - 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) - 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. +Sequence Concat operator + +The sequence_concat operator concatenates multiple LoDTensors. +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. +- Case1: + 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 + information of the output keeps the same as the input. + + 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) + LoD(Out) = {{0,2,4}, {0,1,2,3,4}}; Dims(Out) = (4,7,4) + +- Case2: + 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. + + 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) + LoD(Out) = {{0,5,9}, {0,1,2,3,4,5,6,7,9}}; Dims(Out) = (9,3,4) + +- Case3: + If the axis is 0(here, level is 1). + + 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) + 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"); } }; diff --git a/paddle/operators/sgd_op.cc b/paddle/operators/sgd_op.cc index 939176c73dc..72f4e4d5cbc 100644 --- a/paddle/operators/sgd_op.cc +++ b/paddle/operators/sgd_op.cc @@ -45,15 +45,17 @@ class SGDOpMaker : public framework::OpProtoAndCheckerMaker { public: SGDOpMaker(framework::OpProto* proto, framework::OpAttrChecker* op_checker) : OpProtoAndCheckerMaker(proto, op_checker) { - AddInput("Param", "Input parameter"); - AddInput("LearningRate", "Learning rate of SGD"); - AddInput("Grad", "Input gradient"); - AddOutput("ParamOut", "output parameter"); + AddInput("Param", "(Tensor) Input parameter"); + AddInput("LearningRate", "(Tensor) Learning rate of SGD"); + AddInput("Grad", "(Tensor) Input gradient"); + AddOutput("ParamOut", "(Tensor) Output parameter"); 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"); } diff --git a/paddle/operators/sign_op.cc b/paddle/operators/sign_op.cc index 1b2f879d6d3..08bf2e4e7cc 100644 --- a/paddle/operators/sign_op.cc +++ b/paddle/operators/sign_op.cc @@ -38,9 +38,10 @@ class SignOpMaker : public framework::OpProtoAndCheckerMaker { : OpProtoAndCheckerMaker(proto, op_checker) { AddInput("X", "(Tensor) Input 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"); } }; diff --git a/paddle/operators/split_op.cc b/paddle/operators/split_op.cc index 1ef314b77f0..275b25e96aa 100644 --- a/paddle/operators/split_op.cc +++ b/paddle/operators/split_op.cc @@ -67,30 +67,38 @@ class SplitOpMaker : public framework::OpProtoAndCheckerMaker { public: SplitOpMaker(framework::OpProto *proto, framework::OpAttrChecker *op_checker) : OpProtoAndCheckerMaker(proto, op_checker) { - AddInput("X", "the input tensor of split operator."); - AddOutput("Out", "the output tensors of split operator.").AsDuplicable(); + AddInput("X", "(Tensor) Input tensor of the split operator."); + AddOutput("Out", "(Tensor) Output tensors of the split operator.") + .AsDuplicable(); AddComment(R"DOC( - Split the input tensor into multiple sub-tensors. - Example: - Input = [[1,2], - [3,4], - [5,6]] - sections = [2,1] - axis = 0 - Output[0] = [[1,2], - [3,4]] - Output[1] = [[5,6]] +Split operator + +This operator splits the input tensor into multiple sub-tensors. + +Example: + Input = [[1,2], + [3,4], + [5,6]] + sections = [2,1] + axis = 0 + Output[0] = [[1,2], + [3,4]] + Output[1] = [[5,6]] )DOC"); AddAttr>("sections", - "the length for each" - "output along with the specify axis.") + "(vector) " + "the length of each output along the " + "specified axis.") .SetDefault(std::vector{}); AddAttr("num", - "number of the sub-tensors, it must evenly divide " + "(int, default 0)" + "Number of sub-tensors. This must evenly divide " "Input.dims()[axis]") .SetDefault(0); - AddAttr("axis", "The axis which the input will be splited on.") + AddAttr("axis", + "(int, default 0) " + "The axis which the input will be splited on.") .SetDefault(0); } }; diff --git a/paddle/operators/squared_l2_distance_op.cc b/paddle/operators/squared_l2_distance_op.cc index e360c19b47e..bec2a2c18ae 100644 --- a/paddle/operators/squared_l2_distance_op.cc +++ b/paddle/operators/squared_l2_distance_op.cc @@ -59,23 +59,26 @@ class SquaredL2DistanceOpMaker : public framework::OpProtoAndCheckerMaker { SquaredL2DistanceOpMaker(framework::OpProto* proto, framework::OpAttrChecker* op_checker) : OpProtoAndCheckerMaker(proto, op_checker) { - AddInput("X", "Input of SquaredL2DistanceOp."); - AddInput("Y", "Target of SquaredL2DistanceOp."); + AddInput("X", "(Tensor) Input of SquaredL2DistanceOp."); + AddInput("Y", "(Tensor) Target of SquaredL2DistanceOp."); AddOutput("sub_result", - "Buffering substraction result which " + "(Tensor) Buffering subtraction result which " "will be reused in backward.") .AsIntermediate(); - AddOutput("Out", "Squared l2 distance between input and target."); + AddOutput("Out", "(Tensor) Squared l2 distance between input and target."); AddComment(R"DOC( - SquaredL2DistanceOp will cacluate the squared L2 distance for - input and target. Number of distance value equals to the - first dimension of input. First dimension of target could be equal to - input or to 1. If the first dimension of target is 1, SquaredL2DistanceOp - will broadcast target's first dimension to input's first dimension. - You can decide whether calculate the gradient of input and target. - - Both the input X and Y can carry the LoD (Level of Details) information, - or not. But the output only shares the LoD with input X. +SquaredL2Distance operator + +This operator will cacluate the squared L2 distance for the input and +the target. Number of distance value will be equal to the first dimension +of input. First dimension of the target could be equal to the input or to 1. +If the first dimension of target is 1, the operator will broadcast target's +first dimension to input's first dimension. During backward propagation, +the user can decide whether to calculate the gradient of the input or +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"); } }; diff --git a/paddle/operators/squared_l2_norm_op.cc b/paddle/operators/squared_l2_norm_op.cc index 42ad87e65a8..3c10e6159f4 100644 --- a/paddle/operators/squared_l2_norm_op.cc +++ b/paddle/operators/squared_l2_norm_op.cc @@ -52,13 +52,13 @@ class SquaredL2NormOpMaker : public framework::OpProtoAndCheckerMaker { framework::OpAttrChecker* op_checker) : framework::OpProtoAndCheckerMaker(proto, op_checker) { 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( SquaredL2Norm Operator. Computes the squared L2 norm of a tensor. -Out = sum (X ** 2) +$$Out = \sum_{i} X_{i}^2$$ )DOC"); } diff --git a/paddle/operators/sum_op.cc b/paddle/operators/sum_op.cc index ca36ad764c8..d9d3dd6e37a 100644 --- a/paddle/operators/sum_op.cc +++ b/paddle/operators/sum_op.cc @@ -45,13 +45,15 @@ class SumOpMaker : public framework::OpProtoAndCheckerMaker { public: SumOpMaker(framework::OpProto* proto, framework::OpAttrChecker* op_checker) : OpProtoAndCheckerMaker(proto, op_checker) { - AddInput("X", "the input tensors of sum operator.").AsDuplicable(); - AddOutput("Out", "the output tensor of sum operator."); + AddInput("X", "(vector) The input tensors of sum operator.") + .AsDuplicable(); + AddOutput("Out", "(Tensor) The output tensor of sum operator."); AddComment(R"DOC( -Sum the input tensors. +Sum operator. -All the inputs can carry the LoD (Level of Details) information, -or not. But the output only shares the LoD with the first input. +This operators sums the input tensors. All the inputs can carry the +LoD (Level of Details) information. However, the output only shares +the LoD information with the first input. )DOC"); } }; -- GitLab