Skip to content

T
tic
Commit 8bc7c3e4 by Minjie Wang Committed by Tianqi Chen
Options

Fix comments while reading the codes. (#42)

parent 67179f78
Showing with 118 additions and 86 deletions
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<Graph (Graph src)> 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<std::string>& pass);
......@@ -52,36 +53,39 @@ struct PassFunctionReg
/*! \brief generated targets of graph attributes */
std::vector<std::string> 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);
......
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,
......
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<NodeEntry> 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<NodePtr> 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<std::string> 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<std::string> 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<const Symbol*>& args,
const std::unordered_map<std::string, const Symbol*>& 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<const Symbol*>& args,
const std::unordered_map<std::string, const Symbol*>& 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<std::pair<std::string, std::string> >& 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<std::string, std::string> 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<std::string, std::string> 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<Symbol>& symbols);
};
......
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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment