diff --git a/include/aidge/graph/Node.hpp b/include/aidge/graph/Node.hpp
index c6ac9c651aadbc8b074bc55aa955838ac370746b..7319db245442e1d37fb3489ab289794ec9091f47 100644
--- a/include/aidge/graph/Node.hpp
+++ b/include/aidge/graph/Node.hpp
@@ -43,6 +43,16 @@ class GraphView;
/**
* @brief Object carrying the topological information of the computational graph.
+ * A Node contains :
+ * - mAttrs : the attributes of the Node. If one of them is a name, it should be unique among all other Node name
+ * - mViews: a set of pointers to GraphView instances including this Node instance
+ * - mOperator: a pointer to the Operator associated to the node
+ * - mParents: a vector of parent nodes, which are its inputs
+ * - mIdOutParents: a vector of indexes, corresponding to the connected output index of the parent nodes.
+ * - mChildren: a vector of vector of children nodes, which lists, for each output of the Node, all its children.
+ * - mIdInChildren: a vector of vector of indexes, providing for each children nodes, the input index this node is connected to. The node can be connected to different input of the same child.
+ * - mForward: queue of forward propagation function
+ * - mBackward: queue of backward propagation function
*/
class Node : public std::enable_shared_from_this<Node> {
private:
@@ -76,16 +86,16 @@ public:
Node() = delete;
/**
- * @brief Construct a new Node object associated with the input Operator.
- * @param op Operator giving the Node its number of connections.
- * @param attrs Attributes for the Node.
+ * @brief Construct a new Node object associated with the provided Operator.
+ * @param std::shared_ptr<Operator> op: The Operator held by the Node.
+ * @param std::shared_ptr<DynamicAttributes> attrs: DynamicAttributes of the Node.
*/
Node(std::shared_ptr<Operator> op, std::shared_ptr<DynamicAttributes> attrs);
// Node(std::shared_ptr<Operator> op, const DynamicAttributes& attrs);
/**
- * @brief Construct a new Node object associated with the input Operator.
- * @param op Operator giving the Node its number of connections.
+ * @brief Construct a new Node object associated with the provided Operator.
+ * @param op The Operator of the Node, it determines its number of connections.
* @param name (optional) name for the Node.
*/
Node(std::shared_ptr<Operator> op, const std::string& name = "");
@@ -96,18 +106,34 @@ public:
return lhs.shared_from_this() == rhs.shared_from_this();
}
+ /**
+ * @brief Add a lambda function that will be called before the operator's Forward
+ * @param std::function<bool()> func: The function to add
+ */
void addBeforeForward(std::function<bool()> func) {
mForward.push_front(func);
}
+ /**
+ * @brief Add a lambda function that will be called after the operator's Forward
+ * @param std::function<bool()> func: The function to add
+ */
void addAfterForward(std::function<bool()> func) {
mForward.push_back(func);
}
+ /**
+ * @brief Add a lambda function that will be called before the operator's Backward
+ * @param std::function<bool()> func: The function to add
+ */
void addBeforeBackward(std::function<bool()> func) {
mBackward.push_front(func);
}
+ /**
+ * @brief Add a lambda function that will be called after the operator's Backward
+ * @param std::function<bool()> func: The function to add
+ */
void addAfterBackward(std::function<bool()> func) {
mBackward.push_back(func);
}
@@ -118,9 +144,12 @@ public:
///////////////////////////////////////////////////////
/**
- * @brief Functional operator for user-friendly connection interface using an ordered set of Connectors.
- * @param ctors Ordered Connectors linking their associated Node to the input of the current Node with the same index.
- * @return Connector
+ * @brief Method to enable the functional declaration of a graph using an ordered set of Connectors.
+ * With this method, the node will register itself to the connector and return a new connector that
+ * contains the list of nodes that have been called.
+ * @param std::vector<Connector> ctors: Ordered Aidge::Connector linking their associated Node to the input of the current Node with the same index.
+ * @warning length of ctors must be lower than the number of inputs of the Node
+ * @return Connector: the new connector of the Node
*/
Connector operator()(const std::vector<Connector> &ctors);
@@ -128,37 +157,42 @@ public:
///////////////////////////////////////////////////////
// INNER
///////////////////////////////////////////////////////
-
+ /**
+ * @brief Returns the attributes of the Node.
+ * @return std::shared_ptr<DynamicAttributes>: The DynamicAttributes of the Node.
+ */
inline std::shared_ptr<DynamicAttributes> attributes() const {
return mAttrs;
}
+
/**
- * @brief Name of the Node.
- * @return std::string
+ * @brief Returns the name of the Node.
+ * @warning name is not mandatory and may be empty.
+ * @return std::string: The Name of the Node
*/
std::string name() const noexcept { return mAttrs->getAttr<std::string>("name"); }
/**
- * @brief Set the Node name.
- * @warning Undefined behavior when several Nodes have the same name.
- * @param name New name for the node.
+ * @brief Set the Node's Name.
+ * @warning Undefined behaviour when several Nodes have the same name, use Node::createUniqueName to avoid complications.
+ * @param std::string name: New name for the node.
*/
void setName(const std::string &name);
/**
* @brief Given the parameter name generate a new name which is unique
- * in all the GraphView which contains this node.
- * To generate the new name the method is called recursively and append
- * the character ``_``.
- * If no duplicate return name, this is the exit condition.
- * @param name Base name to make unique.
- * @return A unique name in all the GraphView which contains this one.
+ * in all the GraphView which contains this Node.
+ * @details if the provided name is not yet used, it will be used as is
+ * else, the returned name will be "name_X"
+ * name being the value provided by the name argument and X the smaller integer allowing name uniqueness.
+ * @param std::string name: Base name to make unique.
+ * @return std::string A name not used in any of the GraphView which contains this node.
*/
std::string createUniqueName(std::string name);
/**
- * @brief Type of the node.
- * @return std::string
+ * @brief Type of the Node's operator.
+ * @return std::string the type of the Node's operator
*/
inline std::string type() const { return mOperator->type(); }
@@ -167,18 +201,18 @@ public:
///////////////////////////////////////////////////////
/**
- * @brief Run forward() function of the associated Operator.
+ * @brief Run Operator::forward() function of the associated Operator.
*/
void forward();
/**
- * @brief Run backward() function of the associated Operator.
+ * @brief Run Operator::backward() function of the associated Operator.
*/
void backward();
/**
- * @brief Get the Operator object of the Node.
- * @return std::shared_ptr<Operator>
+ * @brief Get the Operator help by the Node.
+ * @return std::shared_ptr<Operator> the Operator held by the Node
*/
inline std::shared_ptr<Operator> getOperator() const { return mOperator; }
// inline std::shared_ptr<Operator> getOperator() const { return mOperator; }
@@ -188,63 +222,63 @@ public:
///////////////////////////////////////////////////////
/**
- * @brief Whether or not every input of the Node is linked to a Parent.
- * If true then the Node is ready to be executed.
- * @return true
- * @return false
+ * @brief Whether or not every input of the Node are linked to a Parent.
+ * @return bool: True if every input of the Node are linked to a Parent, false otherwise.
*/
bool valid() const;
/**
- * @brief List of pair <Parent, ID of the data input>. When an input is not
- * linked to any Parent, the pair is <nullptr, gk_IODefaultIndex>.
+ * @brief Returns the input parents of the Node.
+ * @details When an input is not linked to any Parent, the pair is <nullptr, gk_IODefaultIndex>.
* Data inputs exclude inputs expecting parameters (weights or bias).
- * @return std::vector<std::pair<std::shared_ptr<Node>, IOIndex_t>>
+ * @return std::vector<std::pair<std::shared_ptr<Node>, IOIndex_t>> : List of the pairs <Parent, output ID of the Parent> of the Node's inputs.
*/
std::vector<std::pair<NodePtr, IOIndex_t>> dataInputs() const;
/**
- * @brief List of pair <Parent, ID of the parent output>. When an input is not linked
- * to any Parent, the pair is <nullptr, gk_IODefaultIndex>.
- * @return std::vector<std::pair<std::shared_ptr<Node>, IOIndex_t>>
+ * @brief Returns the inputs of the Node.
+ * @details When an input is not linked to any Parent, the pair is <nullptr, gk_IODefaultIndex>.
+ * As opposed to dataInputs(), inputs() includes parent nodes containing parameters (e.g. weights or biases)
+ * @return std::vector<std::pair<std::shared_ptr<Node>, IOIndex_t>> : List of the pairs <Parent, output ID of the Parent> of the Node's inputs.
*/
std::vector<std::pair<NodePtr, IOIndex_t>> inputs() const;
/**
- * @brief List of names. When an input is not linked
- * to any Parent, the value is "".
+ * @brief Return a vector of the name of the inputs of the Node
+ * The vector has the same order of the Node inputs.
* @return std::vector<std::string>
*/
std::vector<std::string> inputsNames() const;
/**
- * @brief Parent and its output Tensor ID linked to the inID-th input Tensor.
+ * @brief Accessor of <parent_node, parent_node_output> linked to the inID-th input input of this node.
* If the input is not linked to any Parent, the pair is <nullptr, gk_IODefaultIndex>.
- * @param inID
- * @return std::pair<std::shared_ptr<Node>, IOIndex_t>
+ * @param IOIndex_t inID : the ID of the input we want to know the parent of
+ * @return std::pair<std::shared_ptr<Node>, IOIndex_t>: The pair <Parent, output ID of the Parent> of the Node's inID-th input.
*/
std::pair<std::shared_ptr<Node>, IOIndex_t> input(const IOIndex_t inID) const;
/**
- * @brief Name of the input.
+ * @brief Return the name of the inId-th input of the Node.
* @param inID
* @return std::string
*/
std::string inputName(const IOIndex_t inID) const;
/**
- * @brief Update Name of the input.
+ * @brief Update the name of the inId-th input of the Node.
* @param inID
* @param newName
- * @return std::string
+ * @return std::string the updated name
*/
std::string inputName(const IOIndex_t inID, std::string newName);
/**
* @brief Get the lowest index in the InputData Parent list equal to the
- * nullptr.
+ * nullptr (i.e. the ID of the first free data input).
* Data inputs exclude inputs expecting parameters (weights or bias).
- * @return std::size_t
+ * if there is no free input, will return gk_IODefaultIndex (max of uint16)
+ * @return IOIndex_t: the index of the first free (parentless) data input.
*/
inline IOIndex_t getFirstFreeDataInput() const {
IOIndex_t i = 0;
@@ -258,33 +292,39 @@ public:
return (i < nbInputs()) ? i : gk_IODefaultIndex;
}
-
+ /**
+ * @brief Returns the number of free data inputs of the Node
+ * (i.e. data inputs that are not linked to an other node)
+ * @note Node cannot run until all of its mandatory inputs are filled
+ * @return IOIndex_t: the number of free (parentless) data inputs
+ */
IOIndex_t getNbFreeDataInputs() const;
/**
- * @brief List input ids of children linked to outputs of the node. The vector
- * size is guaranteed to match the number of outputs of the node. If there is
- * no connection to a given output, the corresponding sub-vector will be empty.
- * @return std::vector<std::vector<std::pair<std::shared_ptr<Node>,
- * IOIndex_t>>>
+ * @brief Returns the outputs of the Node.
+ * @details The parent vector size matches the number of outputs of the node.
+ * Each sub-vector size will match the number of children connected to the n-th output (i.e. if 3 nodes are connected to the 3rd output parent_vec[3].size() == 3).
+ * @return std::vector<std::vector<std::pair<std::shared_ptr<Node>, IOIndex_t>>>: Vector of vectors of children of the Node and the ID of the child's input linked to the current Node.
*/
std::vector<std::vector<std::pair<NodePtr, IOIndex_t>>> outputs() const;
-
+ /**
+ * @brief Return a vector of the name of the output of the Node
+ * The vector has the same order of the Node outputs.
+ * @return std::vector<std::string>
+ */
std::vector<std::string> outputsNames() const;
/**
- * @brief Children and their input Tensor ID linked to the outId-th output
- * Tensor.
- * @param outId
- * @return std::vector<std::pair<std::shared_ptr<Node>, IOIndex_t>>
+ * @brief Lists Nodes and input ids of children linked to specified output of the Node
+ * @param IOIndex_t outId: ID of the output from which we want to know the children
+ * @return std::vector<std::pair<std::shared_ptr<Node>, IOIndex_t>> vector of children of the Node's outId's output and the ID of the child's input linked to the current Node.
*/
- std::vector<std::pair<NodePtr, IOIndex_t>>
- output(IOIndex_t outId) const;
+ std::vector<std::pair<NodePtr, IOIndex_t>> output(IOIndex_t outId) const;
/**
- * @brief Return the output name of the Node for index.
+ * @brief Return the name of the outId-th output of the Node.
* @param outId
* @return std::string
*/
@@ -292,7 +332,7 @@ public:
/**
- * @brief Update the output name of the Node for index.
+ * @brief Update the name of the outId-th output of the Node.
* @param outId
* @param newName
* @return std::string
@@ -301,15 +341,17 @@ public:
/**
* @brief Number of inputs, including both data and learnable parameters.
- * @details [data, data, weight, bias] => 4
- * @return IOIndex_t
+ * @details ex: [data, data, weight, bias] => 4
+ * @return IOIndex_t : The number of inputs of the Node's Operator
*/
inline IOIndex_t nbInputs() const noexcept { return mOperator->nbInputs(); }
/**
- * @brief Category of a specific input (Data or Param, optional or not).
+ * @brief Returns the category of a specific input (Data or Param, optional or not).
* Data inputs exclude inputs expecting parameters (weights or bias).
- * @return InputCategory
+ * @details ex: with [datatype1, datatype2, weight, bias], inputCategory(1) returns datatype2
+ * @param IOIndex_t idx: The index of the input for which we determine the category.
+ * @return InputCategory: the category of the specified input
*/
inline InputCategory inputCategory(IOIndex_t idx) const {
return mOperator->inputCategory(idx);
@@ -317,9 +359,9 @@ public:
/**
* @brief Returns whether the given node parent index is a back edge
- * A back edge is defined by the operator and node parent index
- * correspond to operator input index.
- * @return true if the operator defines it as a back edge
+ * A back edge is an edge from a Node to one of its ancestor.
+ * @param IOIndex_t idx!: Index of the Node's connection we want to test
+ * @return bool: True if the operator defines it as a back edge, False otherwise
*/
inline bool parentIsBackEdge(IOIndex_t idx) const {
return mOperator->isBackEdge(idx);
@@ -327,16 +369,24 @@ public:
/**
* @brief Number of inputs linked to a Parent's output.
- * @return IOIndex_t
+ * @warning Unconnected Inputs will throw errors when compiling graph.
+ * @return IOIndex_t: The number of inputs that have a parent.
*/
IOIndex_t nbValidInputs() const;
/**
- * @brief Getter for the number of Output Tensors of the Node.
- * @return IOIndex_t
+ * @brief Getter for the number of Outputs of the Node.
+ * @return IOIndex_t, the number of outputs of the Node's Operator
*/
inline IOIndex_t nbOutputs() const noexcept { return mOperator->nbOutputs(); }
+
+ /**
+ * @brief Number of outputs linked to a Child's input.
+ * @details each output ID are counted once.
+ * So if two Nodes are connected to the 0-th output they will count as one valid output.
+ * @return IOIndex_t: The number of outputs that have at least a child.
+ */
IOIndex_t nbValidOutputs() const;
///////////////////////////////////////////////////////
@@ -345,31 +395,36 @@ public:
/**
* @brief Set of pointers to each GraphView containing this Node
- * @return std::set<GraphView>
+ * @return std::set<GraphView>: the set of GraphView containing this Node
*/
std::set<std::shared_ptr<GraphView>> views() const noexcept;
/**
* @brief Add a GraphView pointer to the list of GraphView containing
- * the current Node. This feature allows transparent GraphViews.
- * @param graphPtr Pointer to GraphView to add to the list.
+ * the current Node.
+ * @param std::shared_ptr<GraphView> graphPtr Weak pointer to GraphView to add to the list.
*/
inline void addView(const std::shared_ptr<GraphView> &graphPtr) {
mViews.insert(std::weak_ptr<GraphView>(graphPtr));
}
+ /**
+ * @brief Remove the reference of this Node to the GraphView passed as argument.
+ * @warning This function does not remove the reference of the GraphView to the Node.
+ * As such, this function is used in other function and should be not used as is by an user
+ * @param std::shared_ptr<GraphView> graphPtr: Pointer to GraphView to remove from the list.
+ */
void removeView(const std::shared_ptr<GraphView> &graphPtr) {
mViews.erase(graphPtr);
}
/**
- * @brief Link another Node to an output of the current Node.
- * @param otherNode Pointer to the other Node.
- * @param outId ID of the current Node output to connect to the other Node.
+ * @brief Link an other Node to an output of the current Node.
+ * @param NodePtr otherNode: Pointer to the other Node.
+ * @param IOIndex_t outId: ID of the current Node output to connect to the other Node.
* Default to 0.
- * @param otherInId ID of the other Node input to connect to the current Node.
+ * @param IOIndex_t otherInId: ID of the other Node input to connect to the current Node.
* Default to the first available data input.
- *
* @note otherNode shared_ptr is passed by reference in order to be able to detect
* possible dangling connection situations in debug using ref counting.
*/
@@ -378,15 +433,13 @@ public:
IOIndex_t otherInId = gk_IODefaultIndex);
/**
- * @brief Link a Node from a specific GraphView to the current Node.
- * @param otherView Pointer to the GraphView whose content should be
+ * @brief Link an input Node from a specific GraphView to the current Node.
+ * @param std::shared_ptr<GraphView> otherView: Pointer to the GraphView whose content should be
* linked to the current Node.
- * @param outId ID of the output Tensor to connect to the other Node.
+ * @param IOIndex_t outId: ID of the output Tensor to connect to the other Node.
* Default to 0.
- * @param otherInId Pair of pointer to Node and Tensor ID for specifying the
- * connection. If the GraphView whose content is linked has only one input
- * Node, then it defaults to the first available data input Tensor of this
- * Node.
+ * @param std::pair<NodePtr, IOIndex_t> otherInId: Pair of pointer to Node and Tensor ID for specifying the connection.
+ * Default pair is (nullptr, gk_IODefaultIndex), leading to an exception.
*/
void addChild(std::shared_ptr<GraphView> otherView,
const IOIndex_t outId = IOIndex_t(0),
@@ -394,16 +447,17 @@ public:
std::pair<NodePtr, IOIndex_t>(nullptr, gk_IODefaultIndex));
/**
- * @brief Get the list of parent Nodes. As an input is linked to a unique Node,
- * if none is linked then the parent is a nullptr.
- * @return std::vector<std::shared_ptr<Node>>
+ * @brief Return the list of parent Nodes.
+ * Each input can only be linked to one Node.
+ * If an input has no linked node, the associated parent is nullptr
+ * @return std::vector<std::shared_ptr<Node>> The vector of parent Nodes
*/
std::vector<NodePtr> getParents() const;
/**
* @brief Get the pointer to parent of the specified input index. This pointer is nullptr if no parent is linked.
- * @param inId Input index.
- * @return std::shared_ptr<Node>&
+ * @param IOIndex_t inId: Input index.
+ * @return std::shared_ptr<Node>& the pointer to the parent of the specified input
*/
inline NodePtr &getParent(const IOIndex_t inId) {
return mParents.at(inId);
@@ -412,42 +466,56 @@ public:
/**
* @brief Unlink the parent Node at the specified input index and return its pointer.
* Return a nullptr is no parent was linked.
- * @param inId Input index.
- * @return std::shared_ptr<Node>
+ * @param IOIndex_t inId: Input index.
+ * @return std::shared_ptr<Node> the pointer to the parent of the specified input
*/
NodePtr popParent(const IOIndex_t inId);
+ /**
+ * @brief unlinks the parent from the Node and replaces it with nullptr (for coherence with remaining parents)
+ * @param IOIndex_t inId: Input index of the parent to be removed
+ * @return std::bool True if parent has been removed, false otherwise.
+ */
bool removeParent(const IOIndex_t inId);
/**
- * @brief Get the set of pointers to children Nodes linked to the current Node.object.
- * @details The returned set does not include any nullptr as an output maybe linked to
- * an undifined number of Nodes. It does not change the computation of its associated Operator.
- * @return std::set<std::shared_ptr<Node>>>
+ * @brief Get the set of pointers to children Nodes linked to the current Node.
+ * @details The returned set does not include any nullptr as an output.
+ * Node that are several times child of this one (several of its input come from this Node) appear only once
+ * @return std::set<std::shared_ptr<Node>>> the set of children of the Node
*/
std::set<NodePtr> getChildren() const;
+ /**
+ * @brief Get all children of the node
+ * @details The parent vector size matches the number of outputs of the node.
+ * Each sub-vector size will match the number of children connected to the n-th output
+ * (i.e. if 3 nodes are connected to the 3rd output parent_vec[2].size() == 3).
+ * @returns std::vector<std::vector<std::shared_ptr<Node>>> The vector (main vector,size=number of outputs)
+ * of vectors (one per output of the Node) of children
+ */
std::vector<std::vector<NodePtr>> getOrderedChildren() const;
/**
* @brief Get the list of children Nodes linked to the output at specified index.
- * @param outId Output index.
- * @return std::vector<std::shared_ptr<Node>>
+ * @param IOIndex_t outId: Output index.
+ * @return std::vector<std::shared_ptr<Node>> Vector of children of the outId-th output
*/
std::vector<NodePtr> getChildren(const IOIndex_t outId) const;
/**
* @brief Remove registered child from children list of specified output if possible.
- * If so, also remove current Node from child Node from parent.
- * @param std::shared_ptr<Node> Node to remove.
- * @param outId Output index. Default 0.
- * @return true Child found and removed for given output index.
- * @return false Child not found at given index. Nothing removed.
+ * If so, also remove current Node from child's parent.
+ * @param NodePtr nodePtr: to remove.
+ * @param IOIndex_t outId: Output index. Default 0.
+ * @return bool True if Child found and removed for given output index, false otherwise
*/
bool removeChild(const NodePtr nodePtr, const IOIndex_t outId = 0);
/**
- * @brief Remove every link of surrounding nodes to it and conversely
+ * @brief Remove every link between this Node and its parents and children
+ * @param bool includeLearnableParam: If False, connections with data and OptionalData are kept,
+ * if true, they are removed as well
*/
void resetConnections(bool includeLearnableParam = false);
@@ -457,26 +525,26 @@ public:
/**
* @brief Clone the current Node. The Operator attribute of the new Node is not copied but shared with the current Node. The new node has no connection.
- * @return NodePtr
+ * @return NodePtr Pointer to the cloned Node
*/
NodePtr cloneSharedOperators() const;
/**
* @brief Clone the Node. Every attribute is copied, even Operator pointer except for Producers for which it is shared. The new Node has no connection.
- * @return NodePtr
+ * @return NodePtr Pointer to the cloned Node
*/
NodePtr cloneSharedProducers() const;
/**
* @brief Clone the Node and its Operator. The new Node has no connection.
- * @return NodePtr
+ * @return NodePtr Pointer to the cloned Node
*/
NodePtr clone() const;
/**
* @brief Callback function to clone the Node keeping the same Operator object instance. The new Node has no connection.
- * @param node Node to clone.
- * @return NodePtr
+ * @param node Node: to clone.
+ * @return NodePtr Pointer to the cloned Node
*/
static NodePtr cloneSharedOperators(NodePtr node) {
return node->cloneSharedOperators();
@@ -484,8 +552,8 @@ public:
/**
* @brief Callback function to clone the Node. Every attribute is copied, even Operator pointer except for Producers for which it is shared. The new Node has no connection.
- * @param node Node to clone.
- * @return NodePtr
+ * @param node Node: to clone.
+ * @return NodePtr Pointer to the cloned Node
*/
static NodePtr cloneSharedProducers(NodePtr node) {
return node->cloneSharedProducers();
@@ -493,14 +561,19 @@ public:
/**
* @brief Callback function to clone the Node and its Operator. The new Node has no connection.
- * @param node Node to clone.
- * @return NodePtr
+ * @param node Node: to clone.
+ * @return NodePtr Pointer to the cloned Node
*/
static NodePtr clone(NodePtr node) {
return node->clone();
}
#ifdef PYBIND
+ /**
+ * @brief Define a string to represent this object.
+ * See python ``__repr__`` method.
+ * @return std::string
+ */
std::string repr() const {
std::string nodeString{fmt::format("Node(name='{}', optype='{}'", name(), type())};
if (mParents.size() > 0) {
@@ -535,9 +608,9 @@ private:
///////////////////////////////////////////////////////
/**
- * @brief Set the idInChildren parameter.
- * @param inID
- * @param newNodeOutID
+ * @brief Updates mIdOutParents by giving the value newNodeOutID to the inID-th member of the list
+ * @param IOIndex_t inID: input of the Node that is being changed
+ * @param IOIndex_t newNodeOutID: updated value, corresponds to the new output of the parent Node
*/
void setInputId(const IOIndex_t inID, const IOIndex_t newNodeOutID);
@@ -546,11 +619,10 @@ private:
///////////////////////////////////////////////////////
/**
- * @brief Add the given Node as a child for the current Node.
- * @param otherNode
- * @param outId
- * @param otherInId
- *
+ * @brief Set the given Node as a child of the current Node.
+ * @param NodePtr otherNode: The new child of the current Node
+ * @param IOIndex_t outId: The output of the current Node that will welcome the new child
+ * @param IOIndex_t otherInId: the input of the new child that welcomes the current Node
* @note otherNode shared_ptr is passed by reference in order to be able to detect
* possible dangling connection situations in debug using ref counting.
*/
@@ -558,20 +630,19 @@ private:
const IOIndex_t otherInId);
/**
- * @brief Add the given GraphView's input Node as a child for the current Node
- * @param otherGraph
- * @param outId
- * @param otherInId pointer the GraphView's input Node and its input index. Defaults to the
- * only input Node if the GraphView has got one.
+ * @brief Set the given GraphView's input Node as a child for the current Node
+ * @param std::shared_ptr<GraphView> otherGraph: Graphview that will take the current Node as parent
+ * @param IOIndex_t outId: The output of the current Node that will be linked to the graphView
+ * @param std::pair<NodePtr, IOIndex_t> otherInId) otherInId: pointer the GraphView's input Node and its input index.
*/
void addChildView(std::shared_ptr<GraphView> otherGraph,
const IOIndex_t outId,
std::pair<NodePtr, IOIndex_t> otherInId);
/**
- * @brief Add a Node to the list of parents.
- * @param otherNode Node to add to parents list.
- * @param inId index for adding the parent.
+ * @brief Set the given Node as a parent of the current Node.
+ * @param NodePtr otherNode: Node to add to parents list.
+ * @param IOIndex_t inId: input index of the Node where the parent will be added.
*/
void addParent(const NodePtr otherNode, const IOIndex_t inId);
diff --git a/python_binding/graph/pybind_Node.cpp b/python_binding/graph/pybind_Node.cpp
index 15a0518cfa37a3aca3086ecf5f2fba9437b80345..2055097a2ecda5d250cbc128281c66b856f36e2f 100644
--- a/python_binding/graph/pybind_Node.cpp
+++ b/python_binding/graph/pybind_Node.cpp
@@ -24,41 +24,69 @@ namespace Aidge {
void init_Node(py::module& m) {
py::class_<Node, std::shared_ptr<Node>>(m, "Node")
.def(py::init<std::shared_ptr<Operator>, const std::string&>(), py::arg("op"), py::arg("name") = "")
+
.def("name", &Node::name,
R"mydelimiter(
- Name of the Node.
+ Return the name of the Node.
+
+ .. warning::
+ name is not mandatory for Nodes and may be empty.
+
+ :return: The name of the Node
+ :rtype: string
)mydelimiter")
- .def("clone", (NodePtr (Node::*)() const) &Node::clone)
+
+ .def("clone", (NodePtr (Node::*)() const) &Node::clone,
+ R"mydelimiter(
+ Clone the Node and its :py:class:`aidge_core.Operator`. The new Node has no connection.
+
+ :return: The new cloned Node
+ :rtype: :py:class:`aidge_core.Node`
+ )mydelimiter")
+
.def("type", &Node::type,
R"mydelimiter(
- Type of the node.
+ :return: the type of the Node's :py:class:`aidge_core.Operator`
+ :rtype: string
)mydelimiter")
.def("attributes", &Node::attributes,
R"mydelimiter(
- Get attributes.
+ :return: The attributes of the Node
+ :rtype: :py:class:`aidge_core.DynamicAttributes`
)mydelimiter")
.def("get_operator", &Node::getOperator,
R"mydelimiter(
- Get the Operator object of the Node.
+ Get the :py:class:`aidge_core.Operator` held by the Node.
+
+ :return: The Node's :py:class:`aidge_core.Operator`
+ :rtype: :py:class:`aidge_core.Operator`
)mydelimiter")
.def("set_name", &Node::setName, py::arg("name"),
R"mydelimiter(
Set the Node name.
+ .. warning::
+ Undefined behavior if an other Node possess teh same name inside the same :py:class:`aidge_core.GraphView`, name uniqueness is not guaranteed by design (names being optional).
+ To ensure generating a unique name, refer to :py:meth:`aidge_core.Node.create_unique_name`.
+
:param name: New name for the node.
:type name: str
- :rtype: str
)mydelimiter")
.def("create_unique_name", &Node::createUniqueName, py::arg("base_name"),
R"mydelimiter(
- Given a base name, generate a new name which is unique in all the GraphViews containing this node.
+ Given a base name, generate a new name which is unique in all the :py:class:`aidge_core.GraphView` containing this node.
+
+ If the provided base_name is not yet used, it will be used as is
+ else, the returned name will be "name_X"
+ name being the value provided by the base_name argument and X the smaller integer allowing name uniqueness.
:param base_name: proposed name for the node.
:type base_name: str
+ :return: A name that is not used in any of the Node's :py:class:`aidge_core.GraphView`
:rtype: str
)mydelimiter")
@@ -72,8 +100,8 @@ void init_Node(py::module& m) {
R"mydelimiter(
Link another Node to an output of the current Node.
- :param other_node: Pointer to the other Node.
- :type other_node: :py:class: Node
+ :param other_node: Pointer to the other Node that will be given as a child to the current Node
+ :type other_node: :py:class:`aidge_core.Node`
:param out_id: ID of the output of the current Node to connect to the other Node. (If Node has 1 output max ID is 0). Default to 0.
:type out_id: int
:param other_in_id: ID of the input of the other Node to connect to the current Node (If the node is a Mul op it has 2 input then Max ID is 1).Default to the first available data input.
@@ -96,13 +124,13 @@ void init_Node(py::module& m) {
py::arg("other_graph"), py::arg("out_id") = 0,
py::arg("other_in_id") = py::none(),
R"mydelimiter(
- Link a Node from a specific GraphView to the current Node.
+ Link a Node from a specific :py:class:`aidge_core.GraphView` to the current Node.
- :param other_view: Pointer to the GraphView whose content should be linked to the current Node.
- :type other_view: :py:class: GraphView
+ :param other_view: Pointer to the :py:class:`aidge_core.GraphView` whose content should be linked to the current Node.
+ :type other_view: :py:class:`aidge_core.GraphView`
:param out_id: ID of the current Node output to connect to the other Node. Default to 0.
:type out_id: int
- :param other_in_id: Pair of Node and input connection ID for specifying the connection. If the GraphView whose content is linked has only one input Node, then it defaults to the first available data input ID of this Node.
+ :param other_in_id: Pair of Node and input connection ID for specifying the connection. If the :py:class:`aidge_core.GraphView` whose content is linked has only one input Node, then it defaults to the first available data input ID of this Node.
:type other_in_id: tuple[:py:class: Node, int]
)mydelimiter")
@@ -111,7 +139,7 @@ void init_Node(py::module& m) {
Get ordered list of parent Node and the associated output index connected to the current Node's inputs.
:return: List of connections. When an input is not linked to any parent, the default value is (None, default_index)
- :rtype: list[tuple[Node, int]]
+ :rtype: list[tuple[:py:class: Node, int]]
)mydelimiter")
.def("inputsNames", &Node::inputsNames,
@@ -119,25 +147,25 @@ void init_Node(py::module& m) {
Get ordered list of the current Node's inputs name.
Names can be changed
- :return: List of connections names. TODO
+ :return: List of connections names.
:rtype: list[str]
)mydelimiter")
.def("input", &Node::input, py::arg("in_id"),
R"mydelimiter(
- Get the parent Node and the associated output index connected to the i-th input of the current Node.
+ Get the parent Node and the associated output index connected to the specified input of the current Node.
:param in_id: input index of the current Node object.
:type in_id: int
- :return: i-th connection. When an input is not linked to any parent, the default value is (None, default_index)
+ :return: The parent Node and the corresponding output index of the specified input of the current Node. When an input is not linked to any parent, the default value is (None, 65535)
:rtype: tuple[Node, int]
)mydelimiter")
.def("inputName", py::overload_cast<IOIndex_t>(&Node::inputName, py::const_), py::arg("in_id"),
R"mydelimiter(
- Get the name of the connection of the Node.
+ Get the name of the in_id-th input of the Node.
- :param in_id: input index of the input Node object.
+ :param in_id: input index.
:type in_id: int
:return: i-th connection name.
:rtype: str
@@ -145,9 +173,9 @@ void init_Node(py::module& m) {
.def("inputName", py::overload_cast<IOIndex_t, std::string>(&Node::inputName), py::arg("in_id"), py::arg("newName"),
R"mydelimiter(
- Update the name of the connection Node.
+ Update the name of the in_id-th input of the Node.
- :param in_id: input index of the current Node object.
+ :param in_id: input index.
:type in_id: int
:param newName: input index of the current Node object.
:type newName: str
@@ -158,8 +186,10 @@ void init_Node(py::module& m) {
.def("outputs", &Node::outputs,
R"mydelimiter(
Get, for each output of the Node, a list of the children Node and the associated input index connected to it.
+ The parent list size matches the number of outputs of the node.
+ Each sub-list size will match the number of children connected to the n-th output (i.e. if 3 nodes are connected to the 3rd output parent_list[2].size() == 3).
- :return: List of a list of connections. When an output is not linked to any child, its list a empty.
+ :return: List of a list of connections. When an output is not linked to any child, its list a empty.
:rtype: list[list[tuple[Node, int]]]
)mydelimiter")
@@ -169,7 +199,8 @@ void init_Node(py::module& m) {
:param out_id: input index of the current Node object.
:type out_id: int
- :return: i-th connection. When an input is not linked to any parent, the default value is (None, default_index)
+ :return: List of Nodes and their inputs that are connected to the specified output.
+ When an input is not linked to any parent, the default value is (None, default_index)
:rtype: list[tuple[Node, int]]
)mydelimiter")
@@ -205,8 +236,9 @@ void init_Node(py::module& m) {
.def("get_nb_inputs", &Node::nbInputs,
R"mydelimiter(
- Number of inputs.
+ Gives the number of inputs of the Node.
+ :return: The number of inputs of the Node
:rtype: int
)mydelimiter")
@@ -215,31 +247,55 @@ void init_Node(py::module& m) {
Category of a specific input (Data or Param, optional or not).
Data inputs exclude inputs expecting parameters (weights or bias).
+ :return: The inputCategory of the idx-th input of the Node
:rtype: InputCategory
)mydelimiter")
.def("get_nb_outputs", &Node::nbOutputs,
R"mydelimiter(
- Number of outputs.
+ Gives the number of outputs of the Node.
+ :return: the number our outputs of the Node
:rtype: int
)mydelimiter")
- .def("get_parent", &Node::getParent, py::arg("in_id"))
-
- .def("get_parents", &Node::getParents,
+ .def("get_parent", &Node::getParent, py::arg("in_id"),
R"mydelimiter(
- Get parents.
+ Get the pointer to parent of the specified input index.
+ This pointer is nullptr if no parent is linked to that input.
+
+ :return: The parent of the specified input
+ :rtype: Node
+ )mydelimiter")
+
+ .def("get_parents", &Node::getParents,R"mydelimiter(
+ Get the list of parent Nodes.
+ Each input can only be linked to one Node.
+ If an input has no linked node, the associated parent is None
+
+ :return: The list of parent Nodes
+ :rtype: List[Node]
)mydelimiter")
.def("get_children", (std::set<std::shared_ptr<Node>> (Node::*)() const) &Node::getChildren,
R"mydelimiter(
- Get children.
+ Get the set of children Nodes linked to the current Node.
+ The returned set does not include unconnected outputs.
+ Node that are several times child of this one (several of its input come from this Node) appear only once
+
+ :return: The set of children of the Node
+ :rtype: Set{Node}
)mydelimiter")
.def("get_ordered_children", &Node::getOrderedChildren,
R"mydelimiter(
- Get ordered children.
+ Get all children of the node
+ The parent vector size matches the number of outputs of the node.
+ Each sub-vector size will match the number of children connected to the n-th output
+ (i.e. if 3 nodes are connected to the 3rd output parent_vec[2].size() == 3).
+
+ :return:The list (main list,size=number of outputs) of lists (one per output of the Node) of children
+ :rtype: List[List[Node]]
)mydelimiter")
.def("__call__",