From 4ec056b9030db8cbacce7da2e54c3b74bab52718 Mon Sep 17 00:00:00 2001 From: Minjie Wang Date: Fri, 9 Sep 2016 18:01:17 -0400 Subject: [PATCH] Fix comments while reading the codes. (#42) --- nnvm/include/nnvm/pass.h | 36 +++++----- nnvm/include/nnvm/pass_functions.h | 55 +++++++++------ nnvm/include/nnvm/symbolic.h | 105 +++++++++++++++++------------ nnvm/include/nnvm/tuple.h | 8 +-- 4 files changed, 118 insertions(+), 86 deletions(-) diff --git a/nnvm/include/nnvm/pass.h b/nnvm/include/nnvm/pass.h index 438226f5c93f..b743d2d5eba0 100644 --- a/nnvm/include/nnvm/pass.h +++ b/nnvm/include/nnvm/pass.h @@ -14,11 +14,12 @@ namespace nnvm { /*! - * \brief A PassFunction is a basic "Operator on Graph" - * It takes a source graph + * \brief A PassFunction is an "Operator on Graph". + * It takes a source graph and return a graph that may or may + * not be the same as the input one. * - * A pass function can either change the graph structure of g, - * generating a new Graph, or add new attributes to the graph. + * A pass function can either change the graph structure (thus, + * generating a new Graph), or add new attributes to the graph. * * \param src The graph to be transformed. * \return The generated graph. @@ -26,10 +27,10 @@ namespace nnvm { typedef std::function PassFunction; /*! - * \brief Apply a series of pass transformations on g. + * \brief Apply a series of pass transformations on the input graph. * \param src The graph to be transformed. * \param pass The name of pass to be applied. - * \return The transformed graph + * \return The transformed graph. */ Graph ApplyPass(Graph src, const std::vector& pass); @@ -52,36 +53,39 @@ struct PassFunctionReg /*! \brief generated targets of graph attributes */ std::vector graph_attr_targets; /*! - * \brief set whether this pass will change graph structure. - * \param v the value to set - * \return reference to self. + * \brief Set whether this pass will change graph structure. + * \param v If true, the pass will change graph structure. + * \return Reference to self. */ PassFunctionReg& set_change_graph(bool v) { // NOLINT(*) change_graph = v; return *this; } /*! - * \brief Declare this pass require operator attribute attr_name to be available. - * \param attr_name Name of the attribute. - * \return reference to self. + * \brief Declare that this pass will generate the given graph attribute name + * once it is applied on the graph. + * \param attr_name Name of the graph attribute. + * \return Reference to self. */ PassFunctionReg& provide_graph_attr(const std::string& attr_name) { // NOLINT(*) graph_attr_targets.push_back(attr_name); return *this; } /*! - * \brief declare this pass require operator attribute attr_name to be available. + * \brief Declare this pass requires the given operator attribute to be + * available before being applied on the graph. * \param attr_name Name of the attribute. - * \return reference to self. + * \return Reference to self. */ PassFunctionReg& depend_op_attr(const std::string& attr_name) { // NOLINT(*) op_attr_dependency.push_back(attr_name); return *this; } /*! - * \brief declare this pass require graph attribute attr_name to be available. + * \brief Declare this pass requires the given graph attribute to be + * available before being applied on the graph. * \param attr_name Name of the attribute. - * \return reference to self. + * \return Reference to self. */ PassFunctionReg& depend_graph_attr(const std::string& attr_name) { // NOLINT(*) graph_attr_dependency.push_back(attr_name); diff --git a/nnvm/include/nnvm/pass_functions.h b/nnvm/include/nnvm/pass_functions.h index 20019726f15a..b94528496e51 100644 --- a/nnvm/include/nnvm/pass_functions.h +++ b/nnvm/include/nnvm/pass_functions.h @@ -33,7 +33,7 @@ inline Graph LoadJSON(const std::string& json_str) { /*! * \brief Save a graph to json, redirects to "SaveJSON" pass. - * \param graph The to be saved. + * \param graph The graph to be saved as json format. * \return The json string. */ inline std::string SaveJSON(Graph graph) { @@ -42,11 +42,14 @@ inline std::string SaveJSON(Graph graph) { } /*! - * \brief Add control flow dependencies between nodes - * To correctly order mutation and read to resolve - * write after read problem and read after write problems. - * \param src source graph - * \return A graph that added control flow dependencies. + * \brief Add control flow dependencies between nodes. + * + * This function will enforce the correct order between + * write (mutable operators) and read (immutable operators) + * to sovle write-after-read and read-after-write problems. + * + * \param src The input graph. + * \return A graph with proper control flow dependencies added. */ inline Graph OrderMutation(Graph src) { return ApplyPass(std::move(src), {"OrderMutation"}); @@ -54,11 +57,12 @@ inline Graph OrderMutation(Graph src) { /*! * \brief Infer shapes in the graph given the information. - * \param graph source graph - * \param shape_inputs The shapes of aruguments to the graph. - * \param shape_attr_key The key to the node attribute that can indicate shape. + * \param graph The input graph. + * \param shape_inputs The shapes of input symbols to the graph. + * \param shape_attr_key The key to the node attribute that can indicate shape. This is + * the place where manual hint for shapes could be injected. * \return A graph with new attribute "shape" containing inferred shape of each NodeEntry. - * The index of ShapeVector is given by graph.indexed_graph().entry_id + * The index of ShapeVector is given by graph.indexed_graph().entry_id. */ inline Graph InferShape(Graph graph, ShapeVector shape_inputs, @@ -74,11 +78,12 @@ inline Graph InferShape(Graph graph, /*! * \brief Infer types in the graph given the information. - * \param graph source graph - * \param dtype_inputs The shapes of inputs to the graph. - * \param dtype_attr_key The key to the node attribute that can indicate shape. - * \return A graph with new attribute "shape" containing inferred shape of each NodeEntry. - * The index of ShapeVector is given by graph.indexed_graph().entry_id + * \param graph The input graph. + * \param dtype_inputs The types of input symbols to the graph. + * \param dtype_attr_key The key to the node attribute that can indicate types. This is + * the place where manual hint for types could be injected. + * \return A graph with new attribute "dtype" containing inferred type of each NodeEntry. + * The index of ShapeVector is given by graph.indexed_graph().entry_id. */ inline Graph InferType(Graph graph, DTypeVector dtype_inputs, @@ -93,10 +98,16 @@ inline Graph InferType(Graph graph, } /*! - * \brief Place the devices - * \param graph source graph - * \param device_group_attr_key The attribute name for hinting the device group. - * \param device_assign_map The assignment map of device + * \brief Place the devices for each operator in the graph. + * + * Current device placement is quite simple. Each operator is assigned to a "group" (stored + * in `device_group_attr_key` attribute). Each group is assigned to a device (stored in + * `device_assign_map` attribute). Operators will be placed to the device assigned to its + * group. Copy operators will be injected if cross device reference happens. + * + * \param graph The input graph. + * \param device_group_attr_key The attribute name for hints of device group. + * \param device_assign_map The assignment map of device. * \param device_copy_op The name of copy op to be inserted when cross device copy happened. * \return A graph with new attribute "device", cotaining device information of each node. */ @@ -112,13 +123,13 @@ inline Graph PlaceDevice(Graph graph, /*! * \brief Get the gradient graph whose outputs are gradients of xs wrt to ys. - * \param graph source graph + * \param graph The input graph. * \param ys The entries we want to take gradient from. * \param xs The input to take gradient with respect to. * \param ys_out_grad The symbol for additional gradient to be propagate back to y. - * \param aggregate_fun aggregation function applied to aggregate the inputs + * \param aggregate_fun Aggregation function applied to aggregate the inputs. * \param mirror_fun Optional mirror function to do mirror optimization and save memory. - * \return A new graph, whose outputs corresponds to inputs of xs. + * \return A new graph, whose outputs correspond to inputs of xs. */ inline Graph Gradient( Graph graph, diff --git a/nnvm/include/nnvm/symbolic.h b/nnvm/include/nnvm/symbolic.h index e153945e65a7..3d7f94ce7b0e 100644 --- a/nnvm/include/nnvm/symbolic.h +++ b/nnvm/include/nnvm/symbolic.h @@ -19,7 +19,13 @@ namespace nnvm { /*! - * \brief Symbol is used to represent the + * \brief Symbol is help class used to represent the operator node in Graph. + * + * Symbol acts as an interface for building graphs from different components + * like Variable, Functor and Group. Symbol is also exported to python front-end + * (while Graph is not) to enable quick test and deployment. Conceptually, + * symbol is the final operation of a graph and thus including all the information + * required (the graph) to evaluate its output value. */ class Symbol { public: @@ -47,42 +53,46 @@ class Symbol { std::vector outputs; /*! - * \brief copy the symbol - * \return a deep copy of the symbolic graph. + * \brief Copy the symbol. + * \return A deep copy of this symbol. */ Symbol Copy() const; /*! - * \brief print the symbol info to output stream. - * \param os the output stream we like to print to + * \brief Print the symbol info to output stream. + * \param os The output stream to print to. */ void Print(std::ostream &os) const; // NOLINT(*) /*! - * \brief get the index th element from the returned tuple. - * \param index index of multi output - * \return the symbol corresponds to the indexed element. + * \brief Get the index-th element from the returned tuple. + * \param index Index of multi output. + * \return The symbol corresponds to the indexed element. */ Symbol operator[] (size_t index) const; /*! - * \brief List the input variable nodes - * \param option The options to list the arguments. + * \brief List the input variable nodes. + * + * The order of the returned list is the same as the order of the input list to `operator()`. * - * The position of the returned list also corresponds to calling position in operator() - * \return the arguments list of this symbol, they can be either named or unnamed (empty string). + * \param option The options to list the arguments. + * \return The arguments list of this symbol, they can be either named or unnamed (empty string). * \sa ListInputOption */ std::vector ListInputs(ListInputOption option) const; /*! * \brief List the input names. - * \param option The options to list the arguments. * - * The position of the returned list also corresponds to calling position in operator() - * \return the arguments list of this symbol, they can be either named or unnamed (empty string). + * The order of the returned list is the same as the order of the input list to `operator()`. + * + * \param option The options to list the arguments. + * \return The arguments list of this symbol, they can be either named or unnamed (empty string). * \sa ListInputOption */ std::vector ListInputNames(ListInputOption option) const; /*! * \brief List the names of outputs for this symbol. - * For normal operators, it is usually symbol node name + "_output" + * + * For normal operators, it is usually symbol node name + "_output". + * * \return get the descriptions of outputs for this symbol. */ std::vector ListOutputNames() const; @@ -92,28 +102,30 @@ class Symbol { * * The rest of the symbols will remain the same name. * - * \param args positional arguments - * \param kwargs keyword arguments for the symbol - * \param name name of returned symbol. + * \param args Positional arguments. + * \param kwargs Keyword arguments for the symbol. + * \param name Name of returned symbol. */ void Compose(const array_view& args, const std::unordered_map& kwargs, const std::string& name); /*! * \brief Apply the symbol as a function, compose with arguments - * This is equivalent to Copy then Compose. - * \param args positional arguments for the symbol - * \param kwargs keyword arguments for the symbol - * \param name name of returned symbol. - * \return a new Symbol which is the composition of current symbol with its arguments + * + * This is equivalent to Copy then Compose. + * + * \param args Positional arguments for the symbol. + * \param kwargs Keyword arguments for the symbol. + * \param name Name of returned symbol. + * \return A new Symbol which is the composition of current symbol with its arguments. */ Symbol operator () (const array_view& args, const std::unordered_map& kwargs, const std::string& name) const; /*! - * \brief Add control flow depenencies to operators involved in symbols. - * For grouped sybmbol, an error will be raised. - * This mutate current symbolic Node. + * \brief Add control flow depenencies to the operators in symbols. + * + * For grouped symbol, an error will be raised. This mutates current symbolic Node. * * \param src The symbols to depend on. */ @@ -121,38 +133,43 @@ class Symbol { /* * \brief Get all the internal nodes of the symbol. * \return symbol A new symbol whose output contains all the outputs of the symbols - * Including input variables and intermediate outputs. + * including input variables and intermediate outputs. */ Symbol GetInternals() const; /*! - * \brief set additional attributes to current node. + * \brief Set additional attributes to current node. + * * This only works for symbol with outputs from single operators. - * For grouped sybmbol, an error will be raised. + * For grouped symbol, an error will be raised. * - * This function mutate the node's symbol and is not recommended. + * This function mutates the node's symbol and is not recommended. * * \param attrs The attributes to set. */ void SetAttrs(const std::vector >& attrs); /*! * \brief Get attributes from the symbol. + * * This only works for symbol with outputs from single operators. - * For grouped sybmbol, an error will be raised. + * For grouped symbol, an error will be raised. + * * \param key Key of the attribute. When key == "name", it returns the name attirbute. - * \param out the output value of the attribute. - * \return true if the attribute exists, false if the attribute do not exist. + * \param out The output value of the attribute. + * \return true If the attribute exists, false if the attribute does not exist. */ bool GetAttr(const std::string& key, std::string* out) const; /*! * \brief Get attribute dictionary from the symbol. - * For grouped sybmbol, an error will be raised. - * \param option If recursive is set, the attributes of all children are retrieved, - * The name of symbol will be pre-pended to each key. + * + * For grouped symbol, an error will be raised. + * + * \param option If recursive flag is set, the attributes of all children are retrieved. + * The name of symbol will be pre-pended to each key. * \return The created attribute. */ std::unordered_map ListAttrs(ListAttrOption option) const; /*! - * \brief create symbolic functor(AtomicSymbol) by given operator and attributes. + * \brief Create symbolic functor(AtomicSymbol) by given operator and attributes. * \param op The operator. * \param attrs The additional attributes. * \return Symbol that can be used to call compose further. @@ -160,15 +177,15 @@ class Symbol { static Symbol CreateFunctor(const Op* op, std::unordered_map attrs); /*! - * \brief create variable symbol node - * \param name name of the variable - * \return the new variable + * \brief Create symbol node representing variable. + * \param name Name of the variable. + * \return The symbol. */ static Symbol CreateVariable(const std::string& name); /*! - * \brief create equivalence of symbol by grouping the symbols together - * \param symbols list of symbols - * \return the grouped symbol + * \brief Create equivalence of symbol by grouping the symbols together. + * \param symbols A list of symbols to be grouped. + * \return The grouped symbol. */ static Symbol CreateGroup(const std::vector& symbols); }; diff --git a/nnvm/include/nnvm/tuple.h b/nnvm/include/nnvm/tuple.h index 326a5d9c6da6..ed5f30e516b0 100644 --- a/nnvm/include/nnvm/tuple.h +++ b/nnvm/include/nnvm/tuple.h @@ -19,11 +19,11 @@ namespace nnvm { typedef uint32_t index_t; /*! - * \brief A dynamic sized array data strcuture - * that is optimized for storing small number of elements with same type. - * Data will be stored in stack when number of elements is small. + * \brief A dynamic sized array data strcuture that is optimized for storing + * small number of elements with same type. * - * It is suitable to hold Shape of Tensor. + * Data will be stored in stack when number of elements is small. + * It is suitable to hold shape of Tensor. * * \tparam ValueType The type of data stored inside tuple. * \sa TShape