---

gnn_node Subnodes API
[gnn_node : Basic Building Block for Gradient Machines.]

---

Detailed Description

This API provides the functionality for connecting and traversing gnn_node trees.

Every gnn_node can be connected to another node, forming a node tree. A node can have a single parent node, called "supernode", and can also have several children nodes, called "subnodes" in libgnn.

A node that contains subnodes is a node that computes a function whose output depends on the result of each of the subnode's functions. Per example, a gnn_stack node is a special node who computes the composition of each of its subnode's functions.

In general, nodes that can have subnodes rarely have own parameters. In libgnn, these nodes are called "constructor" nodes, due to its nature.

Leaf nodes, that is, nodes that can't have subnodes (because it wouldn't make any sense for them) are called "atomic" nodes, because they can't be splitted into simpler nodes.

There are several alternatives to install subnodes. The recommended scheme is the following. First, declare a function with variable number of arguments, that takes the gnn_node to be installed. Then, call the gnn_node_sub_install function, like in this example code:

   // include the header file for variable
   // number of function arguments
   #include <stdarg.h>
   
   ...
   
   // Constructor for my own node type
   int
   gnn_mynode_new (int amount_subnodes, ...)
   {
       va_list argptr; // special data type for argument list
       int     status;

       va_start (argptr, amount_subnodes);
       status = gnn_node_sub_install (node, amount_subnodes, argptr);
       va_end (argptr);

       // do the rest
       ...

Once installed, a subnode at the i-th index can be recovered by calling the gnn_node_sub_get_node_at function.

When destroying a node with gnn_node_destroy, its subnodes are automatically uninstalled.

Functions
int	gnn_node_sub_search_params_recurse (gnn_node *node, const char *type, gnn_pbundle *pb)
	The recursive function for parameters searchs.
int	gnn_node_sub_install_specific (gnn_node *node, int nsub,...)
	Install subnodes.
int	gnn_node_sub_install (gnn_node *node, int nsub, va_list subs)
	Install subnodes.
int	gnn_node_sub_install_node_vector (gnn_node *node, gnn_node_vector *vector)
	Install the nodes in the node vector as subnodes.
int	gnn_node_sub_get_number (gnn_node *node)
	Get the number of subnodes.
gnn_node *	gnn_node_sub_get_node_at (gnn_node *node, int i)
	Get's the node's i-th subnode.
gnn_pbundle *	gnn_node_sub_search_params (gnn_node *node, const char *type)
	Get all subnodes of a given type.

---

Function Documentation

gnn_node* gnn_node_sub_get_node_at (  gnn_node *    node, int    i )

This function returns a pointer to the i-th subnode. Parameters: node  A pointer to an gnn_node. i  The index of the subnode to be retrieved. Returns: The pointer to the i-th subnode or NULL if failed. Definition at line 1676 of file gnn_node.c.

int gnn_node_sub_get_number (  gnn_node *    node )

This function returns the number of direct subnodes of the node. Parameters: node  A pointer to an gnn_node. Returns: Returns the number of subnodes. Definition at line 1659 of file gnn_node.c.

int gnn_node_sub_install (  gnn_node *    node, int    nsub, va_list    subs )

This function installs the given nodes as subnodes. Parameters: node  A pointer to an gnn_node. nsub  The number of subnodes in the list. subs  A va_list (C Standard Library) containing pointers to the subnodes to be installed. Returns: Returns 0 if suceeded. Definition at line 1554 of file gnn_node.c.

int gnn_node_sub_install_node_vector (  gnn_node *    node, gnn_node_vector *    vector )

This function installs the non-NULL nodes in the node vector as subnodes. Parameters: node  A pointer to an gnn_node. vector  A pointer to a gnn_node_vector. Returns: Returns 0 if suceeded. Definition at line 1600 of file gnn_node.c.

int gnn_node_sub_install_specific (  gnn_node *    node, int    nsub, ...    )

This function installs the given nodes as subnodes. Parameters: node  A pointer to an gnn_node. nsub  The number of subnodes. ...  A list of subnodes to be installed. Returns: Returns 0 if suceeded. Definition at line 1527 of file gnn_node.c.

gnn_pbundle* gnn_node_sub_search_params (  gnn_node *    node, const char *    type )

This function searches the whole node three for nodes of the given type, and returns a parameter bundle of all their parameters. Parameters: node  A pointer to an gnn_node. type  A string containing the type of the subnodes to be retrieved. Returns: A gnn_pbundle. Definition at line 1697 of file gnn_node.c.

int gnn_node_sub_search_params_recurse (  gnn_node *    node, const char *    type, gnn_pbundle *    pb )  [static]

This function is invoked by gnn_node Subnodes API. Parameters: node  A pointer to a gnn_node. type  A string identifying the searched nodes. pb  A pointer to a gnn_pbundle. Returns: 0 if succeeded. Definition at line 370 of file gnn_node.c.

---