---

gnn_node : Basic Building Block for Gradient Machines.
[Nodes]

---

Detailed Description

This is the basic building block for libgnn's trainable functions. The gnn_node data type and its programming interface provide the machinery for the construction, composition, evaluation and training of vector functions. The gnn_node structure is optimized for the evaluation of its gradient (with respect to its inputs and its parameters) using the error-backpropagation scheme (a type of cascade-gradient-evaluation).

gnn_node shouldn't be used by themself. Instead, new node types extend the gnn_node data type.

The conventions for notation used throughout this documentation is:

A gnn_node implements a set of vectorial functions that map an input vector of size to an ouput vector of size . This set can be a singleton, or, optionally, it can have a vector of adjustable parameters of size so that

In this case, we will talk about the "generic" function as the "Machine" or the "Model".

A general machine can be built by connecting several subfunctions in a variety of forms. The resulting function can then be feed with inputs to compute its output. Since libgnn's main purpose is to offer a unified way to train this function using the error-backpropagation scheme to compute the function's gradient with respect to its parameters , the gnn_node structure has been designed to provide a simple yet powerful extendable skeleton for the implementation of highly customized models.

The evaluation of the result is the Forward Evaluation, triggered by the gnn_node_evaluate_f function, and the computation of both gradient is called Backward Evaluation, triggered (in order) by gnn_node_evaluate_dx and gnn_node_evaluate_dw .

In order to compute the result and the gradients for one (and only one!) given input example, you should call, in order:

1. gnn_node_evaluate_init : Cleans the old parameter gradient.
2. gnn_node_evaluate_f : Evaluates the output.
3. gnn_node_evaluate_dx : Computes the gradient with respect to its inputs.
4. gnn_node_evaluate_dw : Computes the gradient with respect to its outputs.

The order function calling sequence above must be respected, and repeated for each input example. Nevertheless, it isn't mandatory to perform all steps in the sequence, i.e. if you want to compute only the output, perform only the first two steps; if you don't need the gradient with respect to the paremeters, then don't call gnn_node_evaluate_dw .

More about extensions:

Although all specific extensions have their own specific features, they all are (or can be casted to) a gnn_node. A gnn_node can be manipulated with the following APIs:

• Basic API: This interface provides the basic functionality, such as retrieving the internal attributes, evaluating an input and evaluating its gradients and .
• gnn_node Parameters API : Offers the functionality to change the node's parameters.
• gnn_node Extension API : This interface provides the functions needed for extending a gnn_node for your particular purposes.
• gnn_node Subnodes API : This last interface is also an extension API, but it offers the functions for connecting and traversing a tree of nodes. This is only needed when you want to implement a construction node (a node which groups other nodes).

Modules
gnn_node Parameters API
	Set of functions for the manipulation of a node's parameters.
gnn_node Extension API
	A set of functions for implementing an extension of gnn_node.
gnn_node Subnodes API
	The API for connecting and traversing trees of nodes.
gnn_node_vector : Vector of nodes.
gnn_pbundle : A Unified View of Parameter Sets.
	Provides a unified view of multiple parameters.
gnn_phandle : A Handle for Parameters.
	Handle for managing a set of parameters.
Functions
int	gnn_node_is_root (gnn_node *node)
	Check if node is root node.
const char *	gnn_node_get_type_name (gnn_node *node)
	Get the node's type.
int	gnn_node_input_get_size (gnn_node *node)
	Get the node's input size.
int	gnn_node_output_get_size (gnn_node *node)
	Get the node's output size.
int	gnn_node_destroy (gnn_node *node)
	Destroys the current node.
int	gnn_node_evaluate_f (gnn_node *node, const gsl_vector *x, gsl_vector *y)
	Evaluates the output of the function recursively.
int	gnn_node_evaluate_init (gnn_node *node)
	Initializes the evaluations.
int	gnn_node_evaluate_dx (gnn_node *node, const gsl_vector *dy, gsl_vector *dx)
	Evaluates the gradient .
int	gnn_node_evaluate_dw (gnn_node *node, gsl_vector *dw)
	Evaluates the gradient .

---

Function Documentation

int gnn_node_destroy (  gnn_node *    node )

This function detroys the node given as a parameter: it calls first the installed destructor and the gnn_node Extension API to destroy itself. This is a virtual function: the specific destruction of the node is given by the installed gnn_node::destroy function, and the destruction of the underlying's node structure by itself is performed by gnn_node Extension API. Warning: Only root nodes can be destroyed. Parameters: node  A pointer to an gnn_node. Returns: Returns 0 if succeeded. Definition at line 500 of file gnn_node.c.

int gnn_node_evaluate_dw (  gnn_node *    node, gsl_vector *    dw )

This function computes of the node's function. First, it sets the appropiate values for initiating the recursive evaluation, and then calls gnn_node Extension API. @warning: The gradient will be evaluated at , where is the last evaluated input vector, and is the last parameter vector. Also, it will use the last given for its error-backpropagation. In other words, the buffers used for both gnn_node : Basic Building Block for Gradient Machines. and gnn_node : Basic Building Block for Gradient Machines. shouldn't have changed! Parameters: node  A pointer to an gnn_node. dw  A gsl_vector, where the result should be placed. Returns: Returns 0 if suceeded. Definition at line 653 of file gnn_node.c.

int gnn_node_evaluate_dx (  gnn_node *    node, const gsl_vector *    dy, gsl_vector *    dx )

This function computes of the node's function. First, it sets the appropiate values for initiating the recursive evaluation, and then calls gnn_node Extension API. @warning: The gradient will be evaluated at , where is the last evaluated input vector, and is the last parameter vector. That is, the last values given at gnn_node : Basic Building Block for Gradient Machines.. Parameters: node  A pointer to an gnn_node. dy  The vector. dx  A gsl_vector, where the result should be placed. Returns: Returns 0 if suceeded. Definition at line 609 of file gnn_node.c.

int gnn_node_evaluate_f (  gnn_node *    node, const gsl_vector *    x, gsl_vector *    y )

This function computes the output of the node's function. First, it sets the appropiate values for initiating the recursive evaluation, and then calls gnn_node Extension API. @warning: If you want to compute , then you should not change the content of the input buffer . Parameters: node  A pointer to an gnn_node. x  The input vector of the correct size that should be evaluated. y  A gsl_vector, where the result should be placed. Returns: Returns 0 if suceeded. Definition at line 538 of file gnn_node.c.

int gnn_node_evaluate_init (  gnn_node *    node )

This function initializes the gradient evaluation routines. It should be called before gnn_node Extension API, for every single pattern or input evaluation. The complete sequence for evaluations is: gnn_node : Basic Building Block for Gradient Machines. gnn_node : Basic Building Block for Gradient Machines. gnn_criterion : Basic Criterion Function. gnn_criterion_de gnn_node : Basic Building Block for Gradient Machines. gnn_node : Basic Building Block for Gradient Machines. Parameters: node  A pointer to an gnn_node. Returns: Returns 0 if suceeded. Definition at line 579 of file gnn_node.c.

const char* gnn_node_get_type_name (  gnn_node *    node )

This function returns the node's type: an unique string which identifies a node's type. Generally speaking, the type depends on which constructor function was used to instantiate the node. Per example, gnn_weight_new () creates a "gnn_weight" node, gnn_tanh_new () creates a "gnn_tanh" node. The returned string is owned by the node and should not be freed or manipulated in any other way. Parameters: node  A gnn_node. Returns: A string containing n integer identifying the layer's type. Definition at line 440 of file gnn_node.c.

int gnn_node_input_get_size (  gnn_node *    node )

This function returns the size of the input vector that the current node's function demands for computing its output . Parameters: node  A pointer to an gnn_node. Returns: The input size. Definition at line 458 of file gnn_node.c.

int gnn_node_is_root (  gnn_node *    node )

This function returns 1 if the current node is a root node, or 0 if not. Parameters: node  A gnn_node. Returns: 1 if root node, 0 if not. Definition at line 413 of file gnn_node.c.

int gnn_node_output_get_size (  gnn_node *    node )

This function returns the size of the output vector that the current node's function computes. Parameters: node  A pointer to an gnn_node. Returns: The output size. Definition at line 475 of file gnn_node.c.

---