---

gnn_node.c

Go to the documentation of this file.

/***************************************************************************
 *  @file  gnn_node.c
 *  @brief gnn_node Implementation File.
 *
 *  @date   : 11-08-03 22:45
 *  @author : Pedro Ortega C. <peortega@dcc.uchile.cl>
 *  Copyright  2003  Pedro Ortega C.
 ****************************************************************************/
/*
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU Library General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */



/**
 * @brief The underlying basic building block for composite gradient machines.
 * @defgroup gnn_node_doc gnn_node : Basic Building Block for Gradient Machines.
 * @ingroup  libgnn_node
 *
 * This is the basic building block for \ref libgnn's trainable functions.
 * The \ref gnn_node data type and its programming interface provide the
 * machinery for the construction, composition, evaluation and training
 * of vector functions. The \ref 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).
 *
 * \ref gnn_node shouldn't be used by themself. Instead, new node types extend
 * the \ref gnn_node data type.
 *
 * The conventions for notation used throughout this documentation is:
 *
 * A \ref gnn_node implements a set \f$\mathbb{F}\f$ of vectorial functions
 * \f$f: \mathbb{R}^n \rightarrow \mathbb{R}^m\f$ that map an input vector
 * \f$x\f$ of size \f$n \times 1\f$ to an ouput vector \f$y\f$ of size
 * \f$m \times 1\f$.
 * This set can be a singleton, or,
 * optionally, it can have a vector of adjustable parameters
 * \f$w \in \mathbb{R}^l\f$ of size \f$l \times 1\f$ so that
 * \f[ \mathbb{F} =
 *     \{ f(\cdot) | f(\cdot) = F(\cdot, w), w\in \mathbb{R}^l \}
 * \f]
 * In this case, we will talk about the "generic" function
 * \f$F : \mathbb{R}^{n+l} \rightarrow \mathbb{R}^m\f$ as the "Machine" or
 * the "Model".
 *
 * A general machine \f$F\f$ 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 \ref 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
 * \f$\frac{\partial E}{\partial w}\f$, the \ref 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 <b>Forward Evaluation</b>, triggered
 * by the \ref gnn_node_evaluate_f function, and the computation of both
 * gradient is called <b>Backward Evaluation</b>, triggered (in order) by
 * \ref gnn_node_evaluate_dx and \ref gnn_node_evaluate_dw .
 *
 * <img src="images/gnn_node1.png" border="0">
 *
 * In order to compute the result and the gradients for one (and only one!)
 * given input example, you should call, in order:
 *
 * -# \ref gnn_node_evaluate_init : Cleans the old parameter gradient.
 * -# \ref gnn_node_evaluate_f    : Evaluates the output.
 * -# \ref gnn_node_evaluate_dx   : Computes the gradient with respect to
 *    its inputs.
 * -# \ref 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
 * \ref gnn_node_evaluate_dw .
 *
 *
 * <b>More about extensions:</b>
 *
 * Although all specific extensions have their own specific features, they all
 * are (or can be casted to) a \ref gnn_node. A \ref 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 \f$\frac{\partial E}{\partial x}\f$
 *              and \f$\frac{\partial E}{\partial w}\f$.
 * - \ref gnn_node_param_doc : Offers the functionality to change the node's
 *              parameters.
 * - \ref gnn_node_ext_doc : This interface provides the functions needed for
 *              extending a \ref gnn_node for your particular purposes.
 * - \ref gnn_node_sub_doc : 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).
 *
 *
 */

/**
 * @brief Atomic Nodes.
 * @defgroup gnn_atomic_doc Atomic Nodes.
 * @ingroup  libgnn_node
 *
 * Atomic nodes are implementations of the \ref gnn_node interface that
 * do not depend on subnodes to compute its result and gradients. Most
 * node types are <b>atomic</b>.
 */

/**
 * @brief Constructor Nodes.
 * @defgroup gnn_constructor_doc Constructor Nodes.
 * @ingroup  libgnn_node
 *
 * Constructor nodes are nodes that do depend on subnodes in order to compute
 * the represented function's result and gradients. They usually provide a
 * way to compose modules, like the \ref gnn_serial or \ref gnn_parallel
 * constructor nodes.
 *
 * Constructor nodes are the glue of Gradient Backpropagation Machines.
 *
 */



/******************************************/
/* Include Files                          */
/******************************************/

#include <assert.h>
#include <stdarg.h>
#include <gsl/gsl_block.h>
#include <string.h>
#include "gnn_utilities.h"
#include "gnn_node.h"


/******************************************/
/* Static Definitions                     */
/******************************************/


static void
gnn_node_destroy_structure (gnn_node *node);

static int
gnn_node_default_f (gnn_node      *node,
                    const gsl_vector *x,
                    const gsl_vector *w,
                    gsl_vector       *y );

static int
gnn_node_default_dx (gnn_node *node,
                     const gsl_vector *x,
                     const gsl_vector *w,
                     const gsl_vector *dy,
                     gsl_vector *dx );

static int
gnn_node_default_dw (gnn_node *node,
                     const gsl_vector *x,
                     const gsl_vector *w,
                     const gsl_vector *dy,
                     gsl_vector *dw );

static void
gnn_node_default_destructor (gnn_node *node);

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

/******************************************/
/* Static Implementations                 */
/******************************************/

/**
 * @brief Destroys a \ref gnn_node.
 * @ingroup gnn_node_ext_doc
 *
 * This function destroys the underlying \ref gnn_node structure by freeing
 * the memory associated to the fields of the node and freeing the structure
 * itself. It also calls the \ref gnn_node_destroy function on all subnodes.
 *
 * This function should not be called directly. Instead, \ref gnn_node_destroy
 * should be called instead in order to free also additional resources that
 * could have been allocated specifically for the node's type. Please read also
 * the details available in \ref gnn_node_destroy's documentation.
 *
 * @param node A pointer to a \ref gnn_node.
 */
static void
gnn_node_destroy_structure (gnn_node *node)
{
    int i;
    gnn_node *subnode;
    
    assert (node != NULL);
    
    /* destroy subnodes */
    for (i=0; i<node->nsub; ++i)
    {
        node->sub[i]->super = NULL;
        gnn_node_destroy (node->sub[i]);
    }
    
    /* destroy fields */
    gnn_pbundle_destroy (node->pb);
    gnn_phandle_unref (node->ph);
    free ((char *) node->type);
    
    if (node->sub != NULL)
        free (node->sub);

    /* free node memory */
    free (node);
}

/**
 * @brief Default evaluation function.
 * @ingroup gnn_node_ext_doc
 *
 * This is the default evaluation function for a \ref gnn_node when initialized
 * with NULL in \ref gnn_node_init. It computes
 * \f[ y = [x,x,x,\ldots]^t \f]
 * that is, it copies the input vector \f$x\f$ several times into the output
 * vector until it is completely filled.
 *
 * @param node A pointer to a \ref gnn_node.
 * @param x    The input vector \f$x\f$.
 * @param w    The node's parameter vector \f$w\f$.
 * @param y    The output vector \f$y\f$ where the result should be placed.
 * @return 0 if succeeded.
 */
static int
gnn_node_default_f (gnn_node      *node,
                    const gsl_vector *x,
                    const gsl_vector *w,
                    gsl_vector       *y )
{
    int i;
    int j;
    
    assert (node != NULL);
    
    /* copy input to output several times */
    j = 0;
    while (j < node->m)
    {
        i = 0;
        while (i < node->n && j < node->m)
        {
            gsl_vector_set (y, j, gsl_vector_get (x, i));
            ++j;
            ++i;
        }
    }
    
    return 0;
}

/**
 * @brief Default \f$\frac{\partial E}{\partial x}\f$ evaluation function.
 * @ingroup gnn_node_ext_doc
 *
 * This is the default \f$\frac{\partial E}{\partial x}\f$ evaluation function
 * for a \ref gnn_node when initialized with NULL in \ref gnn_node_init. It
 * computes
 * \f[ ? \f]
 * @todo Not implemented yet.
 *
 * @param node A pointer to a \ref gnn_node.
 * @param x    The input vector \f$x\f$ where the gradient should be evaluated.
 * @param w    The function's parameters \f$w\f$ where the gradient should be
 *             evaluated at.
 * @param dy   The vector \f$\frac{\partial E}{\partial y}\f$ that should
 *             be retropropagated.
 * @param dx   A sufficiently large vector for storing the resulting
 *             \f$\frac{\partial E}{\partial x}\f$ should be placed at.
 * @return 0 if succeeded.
 */
static int
gnn_node_default_dx (gnn_node *node,
                     const gsl_vector *x,
                     const gsl_vector *w,
                     const gsl_vector *dy,
                     gsl_vector *dx )
{
    return 0;
}

/**
 * @brief Default \f$\frac{\partial E}{\partial w}\f$ evaluation function.
 * @ingroup gnn_node_ext_doc
 *
 * This is the default \f$\frac{\partial E}{\partial w}\f$ evaluation function
 * for a \ref gnn_node when initialized with NULL in \ref gnn_node_init. It
 * computes
 * \f[ ? \f]
 * @todo Not implemented yet.
 *
 * @param node A pointer to a \ref gnn_node.
 * @param x    The input vector \f$x\f$ where the gradient should be evaluated.
 * @param w    The function's parameters \f$w\f$ where the gradient should be
 *             evaluated at.
 * @param dy   The vector \f$\frac{\partial E}{\partial y}\f$ that should
 *             be retropropagated.
 * @param dw   A sufficiently large vector for storing the resulting
 *             \f$\frac{\partial E}{\partial w}\f$ should be placed at.
 * @return 0 if succeeded.
 */
static int
gnn_node_default_dw (gnn_node *node,
                     const gsl_vector *x,
                     const gsl_vector *w,
                     const gsl_vector *dy,
                     gsl_vector *dw )
{
    return 0;
}

/**
 * @brief Default \ref gnn_node destructor.
 * @ingroup gnn_node_ext_doc
 *
 * This is the default destructor for a \ref gnn_node when initialized
 * with NULL in \ref gnn_node_init. It asumes that the current \ref gnn_node
 * type hasn't allocated any additional memory nor contains any other specific
 * info other than a \ref gnn_node's default.
 *
 * Consecuently, it doesn't anything than just return.
 *
 * @param node A pointer to a \ref gnn_node.
 */
static void
gnn_node_default_destructor (gnn_node *node)
{
    assert (node != NULL);
    return;
}

/**
 * @brief The recursive function for parameters searchs.
 * @ingroup gnn_node_sub_doc
 *
 * This function is invoked by \ref gnn_node_sub_search_params. 
 *
 * @param node A pointer to a \ref gnn_node.
 * @param type A string identifying the searched nodes.
 * @param pb   A pointer to a \ref gnn_pbundle.
 * @return 0 if succeeded.
 */
static int
gnn_node_sub_search_params_recurse (gnn_node    *node,
                                    const char  *type,
                                    gnn_pbundle *pb)
{
    size_t i;

    assert (node != NULL);

    /* insert parameter handle into parameter bundle if type matches */
    if (strcmp (node->type, type) == 0)
        gnn_pbundle_insert (pb, node->ph, 1);

    /* base case : no more subnodes available */
    if (node->nsub == 0)
        return 0;

    /* recursion case : search all subtrees */
    for (i=0; i<node->nsub; ++i)
        gnn_node_sub_search_params_recurse (node->sub[i], type, pb);

    return 0;
}



/******************************************/
/* Public Interface                       */
/******************************************/

/*************/
/* Basic API */
/*************/

/**
 * @brief Check if node is root node.
 * @ingroup gnn_node_doc
 *
 * This function returns 1 if the current node is a root node, or 0 if not.
 *
 * @param  node A \ref gnn_node.
 * @return 1 if root node, 0 if not.
 */
int
gnn_node_is_root (gnn_node *node)
{
    assert (node != NULL);
    if (node->super == NULL)
        return 1;
    else
        return 0;
}

/**
 * @brief Get the node's type.
 * @ingroup gnn_node_doc
 *
 * 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.
 *
 * @param  node A \ref gnn_node.
 * @return A string containing n integer identifying the layer's type.
 */
const char *
gnn_node_get_type_name (gnn_node *node)
{
    assert (node != NULL);
    return node->type;
}

/**
 * @brief Get the node's input size.
 * @ingroup gnn_node_doc
 *
 * This function returns the size \f$n\f$ of the input vector \f$x\f$ that
 * the current node's function \f$f\f$ demands for computing its output
 * \f$y\f$.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @return The input size.
 */
int
gnn_node_input_get_size (gnn_node *node)
{
    assert (node != NULL);
    return node->n;
}

/**
 * @brief Get the node's output size.
 * @ingroup gnn_node_doc
 *
 * This function returns the size \f$m\f$ of the output vector \f$y\f$ that
 * the current node's function \f$f\f$ computes.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @return The output size.
 */
int
gnn_node_output_get_size (gnn_node *node)
{
    assert (node != NULL);
    return node->m;
}

/**
 * @brief Destroys the current node.
 * @ingroup gnn_node_doc
 *
 * This function detroys the node given as a parameter: it calls first the
 * installed destructor and the \ref gnn_node_destroy_structure to destroy
 * itself.
 *
 * This is a virtual function: the specific destruction of the node is given
 * by the installed \ref gnn_node::destroy function, and the destruction of
 * the underlying's node structure by itself is performed by
 * \ref gnn_node_destroy_structure.
 *
 * @warning Only root nodes can be destroyed.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @return Returns 0 if succeeded.
 */
int
gnn_node_destroy (gnn_node *node)
{
    int i;
    gnn_node *subnode;
    
    assert (node != NULL);
    
    /* check that node isn't subnode */
    if (node->super != NULL)
        GSL_ERROR ("only root nodes can be destroyed", GSL_EINVAL);

    /* call destructor */
    node->destroy (node);

    /* destroy subyacent node structure */
    gnn_node_destroy_structure (node);
    
    return 0;
}

/**
 * @brief Evaluates the output of the function recursively.
 * @ingroup gnn_node_doc
 *
 * This function computes the output of the node's function. First, it sets the
 * appropiate values for initiating the recursive evaluation, and then calls
 * \ref gnn_node_eval_f.
 *
 * @warning: If you want to compute \f$\frac{\partial E}{\partial x}\f$, then
 *           you should not change the content of the input buffer \f$x\f$.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @param  x    The input vector \f$x\f$ of the correct size that should be
 *              evaluated.
 * @param  y    A gsl_vector, where the result should be placed.
 * @return Returns 0 if suceeded.
 */
int
gnn_node_evaluate_f (gnn_node *node, const gsl_vector *x, gsl_vector *y)
{
    assert (node != NULL);

    /* check sizes */
    if (   (x == NULL && node->n != 0)
        || (x != NULL && node->n != x->size))
        GSL_ERROR ("incorrect size of x vector", GSL_EINVAL);

    if (   (y == NULL && node->m != 0)
        || (y != NULL && node->m != y->size))
        GSL_ERROR ("incorrect size of y vector", GSL_EINVAL);

    /* clear y vector */
    gsl_vector_set_zero (y);

    /* call evaluation */
    gnn_node_eval_f (node, x, y);

    return 0;
}

/**
 * @brief Initializes the evaluations.
 * @ingroup gnn_node_doc
 *
 * This function initializes the gradient evaluation routines. It should be
 * called before \ref gnn_node_eval_f, for every single pattern or input
 * evaluation. The complete sequence for evaluations is:
 *
 * - \ref gnn_node_evaluate_init
 * - \ref gnn_node_evaluate_f
 * - \ref gnn_criterion_e
 * - \ref gnn_criterion_de
 * - \ref gnn_node_evaluate_dx
 * - \ref gnn_node_evaluate_dw
 *
 * @param  node A pointer to an \ref gnn_node.
 * @return Returns 0 if suceeded.
 */
int
gnn_node_evaluate_init (gnn_node *node)
{
    assert (node != NULL);

    /* clear gradient */
    gnn_pbundle_set_dw_all (node->pb, 0.0);

    return 0;
}

/**
 * @brief Evaluates the gradient \f$\frac{\partial E}{\partial x}\f$.
 * @ingroup gnn_node_doc
 *
 * This function computes \f$\frac{\partial E}{\partial x}\f$ of the node's
 * function. First, it sets the
 * appropiate values for initiating the recursive evaluation, and then calls
 * \ref gnn_node_eval_dx.
 *
 * @warning: The \f$\frac{\partial E}{\partial x}\f$ gradient will be evaluated
 *           at \f$(x,w)\f$, where \f$x\f$ is the last evaluated input vector,
 *           and \f$w\f$ is the last parameter vector. That is, the last values
 *           given at \ref gnn_node_evaluate_f.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @param  dy   The \f$\frac{\partial E}{\partial y}\f$ vector.
 * @param  dx   A gsl_vector, where the result should be placed.
 * @return Returns 0 if suceeded.
 */
int
gnn_node_evaluate_dx (gnn_node         *node,
                      const gsl_vector *dy,
                      gsl_vector       *dx)
{
    assert (node != NULL);
    assert (dy   != NULL);
    assert (dx   != NULL);

    /* check sizes */
    if (dy->size != node->m)
        GSL_ERROR ("incorrect size of dy vector", GSL_EINVAL);

    if (dx->size != node->n)
        GSL_ERROR ("incorrect size of dx vector", GSL_EINVAL);

    /* clear dx vector */
    gsl_vector_set_zero (dx);
    
    /* call gradient evaluation */
    return gnn_node_eval_dx (node, dy, dx);
}

/**
 * @brief Evaluates the gradient \f$\frac{\partial E}{\partial w}\f$.
 * @ingroup gnn_node_doc
 *
 * This function computes \f$\frac{\partial E}{\partial w}\f$ of the node's
 * function. First, it sets the
 * appropiate values for initiating the recursive evaluation, and then calls
 * \ref gnn_node_eval_dw.
 *
 * @warning: The \f$\frac{\partial E}{\partial w}\f$ gradient will be evaluated
 *           at \f$(x,w)\f$, where \f$x\f$ is the last evaluated input vector,
 *           and \f$w\f$ is the last parameter vector. Also, it will use
 *           the last given \f$\frac{\partial E}{\partial x}\f$ for its
 *           error-backpropagation. In other words, the buffers used for
 *           both \ref gnn_node_evaluate_f and \ref gnn_node_evaluate_dx
 *           shouldn't have changed!
 *
 * @param  node A pointer to an \ref gnn_node.
 * @param  dw   A gsl_vector, where the result should be placed.
 * @return Returns 0 if suceeded.
 */
int
gnn_node_evaluate_dw (gnn_node         *node,
                      gsl_vector       *dw)
{
    int size;

    assert (node != NULL);
    assert (dw   != NULL);

    /* get bundle size */
    size = gnn_pbundle_get_size (node->pb);

    /* check sizes */
    if (size == 0)
        GSL_ERROR ("node doesn't contain any parameters", GSL_EINVAL);

    if (size != dw->size)
        GSL_ERROR ("incorrect size of dw vector", GSL_EINVAL);

    /* call recursive gradient evaluation */
    gnn_node_eval_dw (node);

    /* copy gradient result */
    gnn_pbundle_get_dw (node->pb, dw);

    return 0;
}



/*****************/
/* Parameter API */
/*****************/

/**
 * @brief Set of functions for the manipulation of a node's parameters.
 * @defgroup gnn_node_param_doc gnn_node Parameters API
 * @ingroup gnn_node_doc
 *
 * The Parameter API (Applicaction Programming Interface) provides
 * extended functionality to manipulate a \ref gnn_node's parameters.
 *
 * Every \ref gnn_node contains a set of parameters (it can be empty of
 * course). By changing them, the function's behaviour is changed. Formally,
 * the parameters allow the model to be adapted to a particular case.
 * It is, therefore, very important to provide extended functionality for
 * manipulating them.
 *
 * Every node contains two types of parameters:
 *
 * - The node's own parameters.
 * - The node's total parameters, which are formed by all parameters in the
 *   tree rooted at the current node.
 *
 * Schematically, this can be depicted as (for an atomic node):
 *
 * <img src="images/gnn_node2.png" border="0">
 *
 * When two nodes <i>A</i> and <i>B</i> are composed using a third node
 * <i>C</i>, then <i>C</i> will be at the root, and will provide direct
 * access to all parameters (that is, the parameters of the whole tree):
 *
 *  <img src="images/gnn_node3.png" border="0">
 *
 * This is absolutely transparent to the programmer. Note that each node
 * knows exactly which ones are its local parameters, but to get direct
 * access to them, <b>use the extension API</b>.
 *
 * Note that in general, a node which is not a leaf rarely posseses its own
 * parameters.
 *
 * The good thing here is that you gain direct access to the new
 * (concatenated) parameter as it were a single vector.
 *
 * There are two more objects you should know of: the gradient with respect
 * to the parameters, and the freeze flags, both vectors of the same size
 * as the parameter vector. The first is a buffer, were the gradient should
 * be computed. The second is a special flag vector: they specify if a given
 * parameter is actually free to be changed (free parameter) of if it has
 * been frozen (and can't be changed). These additional vectors can also be
 * manipulated using this interface.
 *
 *
 *
 * <b>Some technical details:</b>
 *
 * So, the node accesses its local parameters (which are some kind of "global"
 * and independent entities that can perfectly be shared with other nodes)
 * through a parameter handle.
 *
 * Simultaneously, the node also posseses a special parameter bundle, which
 * gives him access to the whole tree's parameters.
 *
 * Although it can be useful to know about the internal details of the
 * parameter managing and its implementation, the \ref gnn_node_param_doc
 * provides a transparent set of functions to manipulate them. The important
 * things to note are:
 *
 * - Each node has local and total parameters.
 *
 */
 
 
 
/**
 * @brief Returns the size of the parameter vector.
 * @ingroup gnn_node_param_doc
 *
 * This function returns \f$l\f$, the size of the parameter vector.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @return The size of the parameter vector \f$w\f$.
 */
int
gnn_node_param_get_size (gnn_node *node)
{
    assert (node != NULL);
    return gnn_pbundle_get_size (node->pb);
}

/**
 * @brief Get the node's parameters.
 * @ingroup gnn_node_param_doc
 *
 * This function fills the input buffer w with the node's parameter values.
 *
 * Implementation Note: The parameter vector is build with the node's
 *                      parameter bundle.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @param  w    A gsl_vector sufficiently large to store the values.
 * @return Returns 0 if suceeded.
 */
int
gnn_node_param_get (gnn_node *node, gsl_vector *w)
{
    assert (node != NULL);
    return gnn_pbundle_get_w (node->pb, w);
}

/**
 * @brief Sets new values for the parameter vector.
 * @ingroup gnn_node_param_doc
 *
 * This function sets new values for the node's parameter vector. The new
 * values are taken by the buffer w (of the correct size) given as input
 * argument.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @param  w    A gsl_vector containing the new values for the parameter vector.
 * @return Returns 0 if suceeded.
 */
int
gnn_node_param_set (gnn_node *node, const gsl_vector *w)
{
    assert (node != NULL);
    return gnn_pbundle_set_w (node->pb, w);
}

/**
 * @brief Get the freeze flags.
 * @ingroup gnn_node_param_doc
 *
 * This function fills the given integer vector \a f with the node's freeze
 * flags.
 *
 * Implementation Note: The parameter vector is build with the node's
 *                      parameter bundle.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @param  f    A \c gsl_vector_int sufficiently large to store the values.
 * @return Returns 0 if suceeded.
 */
int
gnn_node_param_freeze_flags_get (gnn_node *node, gsl_vector_int *f)
{
    assert (node != NULL);
    return gnn_pbundle_get_f (node->pb, f);
}

/**
 * @brief Sets new freeze flags.
 * @ingroup gnn_node_param_doc
 *
 * This function sets new freeze flags for the node. They should be given
 * as a \c gsl_vector_int, where 1=freeze and 0=free-parameter.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @param  f    A \c gsl_vector_int containing the new values for the
 *              parameter vector.
 * @return Returns 0 if suceeded.
 */
int
gnn_node_param_freeze_flags_set (gnn_node *node, const gsl_vector_int *f)
{
    assert (node != NULL);
    return gnn_pbundle_set_f (node->pb, f);
}

/**
 * @brief Freeze the i-th parameter.
 * @ingroup gnn_node_param_doc
 *
 * This function freezes the i-th parameter.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @param  i    The index of the parameter to be frozen.
 * @return Returns 0 if suceeded.
 */
int
gnn_node_param_freeze (gnn_node *node, int i)
{
    assert (node != NULL);
    return gnn_pbundle_set_f_at (node->pb, i, 1);
}

/**
 * @brief Unfreeze the i-th parameter.
 * @ingroup gnn_node_param_doc
 *
 * This function unfreezes the i-th parameter.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @param  i    The index of the parameter to be unfrozen.
 * @return Returns 0 if suceeded.
 */
int
gnn_node_param_unfreeze (gnn_node *node, int i)
{
    assert (node != NULL);
    return gnn_pbundle_set_f_at (node->pb, i, 0);
}

/**
 * @brief Check if the i-th parameter is frozen.
 * @ingroup gnn_node_param_doc
 *
 * This function returns 1 if the i-th parameter is frozen.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @param  i    The index of the parameter to be checked.
 * @return Returns 1 if frozen, 0 if not.
 */
int
gnn_node_param_is_frozen (gnn_node *node, int i)
{
    assert (node != NULL);
    return gnn_pbundle_get_f_at (node->pb, i);
}

/**
 * @brief Check if all the node's parameters are frozen.
 * @ingroup gnn_node_param_doc
 *
 * This function returns 1 if all parameters are frozen.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @return Returns 1 if frozen, 0 if not.
 */
int
gnn_node_param_are_frozen (gnn_node *node)
{
    assert (node != NULL);
    if (gnn_pbundle_get_n_free (node->pb) == 0)
        return 1;
    else
        return 0;
}

/**
 * @brief Freeze all parameters.
 * @ingroup gnn_node_param_doc
 *
 * This function freezes all the node's parameters.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @return Returns 0 if suceeded.
 */
int
gnn_node_param_freeze_all (gnn_node *node)
{
    assert (node != NULL);
    return gnn_pbundle_set_f_all (node->pb, 1);
}

/**
 * @brief Unfreeze all parameters.
 * @ingroup gnn_node_param_doc
 *
 * This function unfreezes all the node's parameters.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @return Returns 0 if suceeded.
 */
int
gnn_node_param_unfreeze_all (gnn_node *node)
{
    assert (node != NULL);
    return gnn_pbundle_set_f_all (node->pb, 0);
}

/**
 * @brief Share the node's parameters.
 * @ingroup gnn_node_param_doc
 *
 * This function share the node's parameters with the client node.
 *
 * @warning: This function should be called on nodes that aren't connected only.
 *
 * @param  node   A pointer to an \ref gnn_node.
 * @param  client A pointer to an \ref gnn_node.
 * @return Returns 0 if suceeded.
 */
int
gnn_node_param_share (const gnn_node *node, gnn_node *client)
{
    assert (node   != NULL);
    assert (client != NULL);

    /* check if both nodes haven't any parent nor children */
    if (   (node->super   != NULL)
        || (node->sub     != NULL)
        || (client->super != NULL)
        || (client->sub   != NULL))
        GSL_ERROR ("can't share a connected node's parameters", GSL_EINVAL);

    /* check parameter sizes */
    if (gnn_phandle_get_size (node->ph) != gnn_phandle_get_size (client->ph))
        GSL_ERROR ("can't share parameters of distinct size", GSL_EINVAL);

    /* free the client's parameters */
    gnn_pbundle_destroy (client->pb);
    gnn_phandle_unref (client->ph);

    /* share parameters */
    client->pb = node->pb;
    client->ph = node->ph;

    return 0;
}



/*****************/
/* Extension API */
/*****************/

/**
 * @brief A set of functions for implementing an extension of gnn_node.
 * @defgroup gnn_node_ext_doc gnn_node Extension API
 * @ingroup gnn_node_doc
 *
 * The Extension API (Applicaction Programming Interface) provides
 * extended functionality to program new \ref libgnn node.
 *
 * <b>What is the Extension API's purpose?</b>
 *
 * The Extension API has been designed in order to provide a framework
 * to include custom node types, i.e. nodes that compute a specific
 * function that isn't included in the \ref libgnn distribution.
 *
 * The node types included in the distribution have also been built upon
 * this programming interface.
 *
 * <b>Basics</b>
 *
 * Creating a new node type requires the programmer to implement at least
 * 4 functions, which describe/incarnate the behaviour of the node, and
 * are attached to the new node type.
 *
 * All node types should built upon a basic node type: the \ref gnn_node.
 * The C structure which will implement the node type should contain, as
 * it's first field, a \ref gnn_node, followed by the additional data field
 * the node might need. Per example:
 *
 * \code
   // it's always nice to have a type definition
   typedef struct _myNodeType myNodeType;
 
   // the structure definition
   struct _myNodeType
   {
       gnn_node node;     // the underlying gnn_node
       
       // now comes the rest
       int    exampleField1;
       double exampleField2;
       ...
   }
   \endcode
 *
 * To create a custom node, you should provide a constructor. The constructor
 * should take the needed info to describe your new instance fully. The
 * constructor should allocate memory for the new structure, and initialize
 * the underlying \ref gnn_node, by calling the \ref gnn_node_init function:
 *
 * <i>Example for an Atomic Node Type:</i>
 *
   \code
   // you should return a gnn_node pointer to the new instance
   gnn_node *
   my_node_new (int input_size, int output_size, int param_size, ...)
   {
        gnn_node   *node;
        myNodeType *mynode;

        // allocate memory for your node type
        mynode = (myNodeType *) malloc (sizeof (myNodeType));
        
        // get a pointer to the instance, but viewed as a gnn_node :
        node = (gnn_node *) mynode;
        
        // call the initialization function
        gnn_node_init ( node,
                        "myNodeType",
                        my_node_type_f,
                        my_node_type_dx,
                        my_node_type_dw,
                        my_node_type_dest
                      );

        // if this node were a constructor node,
        // then install the subnodes HERE! In example, calling
        // gnn_node_sub_install_node_vector ...

        // initialize the node sizes
        gnn_node_set_sizes (node, input_size, output_size, param_size);

        // initialize the rest your node type might need
        ...
        
        // finally, return a pointer to the your instance as a gnn_node
        return node;
   }

   \endcode
 *
 * The \ref gnn_node_init function takes a pointer to the node, a string
 * which describes the node type, plus 4 additional functions:
 *
 * -# The evaluation of the function. (\ref gnn_node_f)
 * -# The gradient with respect to the inputs evaluation function.
 *    (\ref gnn_node_df)
 * -# The gradient with respect to the parameters evaluation function.
 *    (\ref gnn_node_df)
 * -# The destructor, which frees the memory. (\ref gnn_node_destructor)
 *
 * Basically, all these functions have specific datatypes that you should
 * respect. All these functions shouldn't access the underlying \ref gnn_node's
 * fields <b>ONLY</b> through the Extension API.
 *
 * <b>Coding Standards</b>
 *
 * The \ref libgnn library has been coded respecting a coding standard that
 * hasn't been documented yet :-) . But basically, you should look at
 * its source code and try to code as similar as posible. Some things you
 * <b>must</b> respect:
 *
 * -# Always provide a \c .h and a \c .c file. The first should contain
 *    the public interface definition, and the second, the implementation.
 *    Always protect the header file with \c #ifdef construct from multiple
 *    inclusion. The implementation should depend <b>only</b> on those
 *    files that it <b>really</b> needs.
 * -# Provide all necessary parameter manipulation functions. This is
 *    very important. Most nodes do have a differente way to view the
 *    parameters, i.e. not as a single vector, but as a vector and a
 *    matrix per example. Then, provide function calls to set new
 *    values and to freeze/unfreeze them. After <b>any</b> manipulation
 *    of parameters, gradients and/or freeze flags, you should call
 *    the \ref gnn_node_local_update routine.
 * -# Be very carefull when you try to optimize the evaluation routines.
 *    It is better to take and use only the objects that have been passed
 *    as arguments. <b>It is a very bad idea to use buffers for speeding up
 *    the cascade-evaluation of gradients!</b> If the gradients <b>do need</b>
 *    values that have been computed previously, then <b>recompute them</b>.
 * -# Document your heavily! There's nothing worse than undocumented source
 *    code, or <b>bad</b> documented code. If you don't want to find yourself
 *    in hell, then provide rich and intelligent documentation. Use the
 *    Doxygen commands to enhance and format.
 *
 */


 
/**
 * @brief Initializes a \ref gnn_node structure.
 * @ingroup gnn_node_ext_doc
 *
 * This function initializes a \ref gnn_node structure. The memory for
 * the structure should be allocated manually. The sizes should be set after
 * calling this function.
 *
 * An example of its use is the following:
 *
   \code
   gnn_node *
   gnn_mifunction (int input_size, int output_size, int param_size)
   {
        gnn_node *node;

        node = (gnn_node *) malloc (sizeof (*node));
        gnn_node_init ( node,
                        "gnn_mifunction",
                        gnn_mifunction_f,
                        gnn_mifunction_dx,
                        gnn_mifunction_dw,
                        gnn_mifunction_dest);

        gnn_node_set_sizes (input_size, output_size, param_size);

        // initialize the rest
        ...
   \endcode
 *
 * If one of the function pointers is NULL, then it installs the
 * default functions:
 * - \ref gnn_node_default_f for    'f = NULL'
 * - \ref gnn_node_default_dedw for 'dedw = NULL'
 * - \ref gnn_node_default_dedx for 'dedx = NULL'
 * - \ref gnn_node_default_destructor for 'dest = NULL'
 *
 * @param node        A pointer to the node to be initialized.
 * @param type        A string containing the name of the layer's type. The
 *                    node will build a copy.
 * @param f     A pointer to the evaluation function.
 * @param dx    A pointer to the \f$\frac{\partial E}{\partial x}\f$ function.
 * @param dw    A pointer to the \f$\frac{\partial E}{\partial w}\f$ function.
 * @param dest  A pointer to the destroy function.
 * @return      0 on success.
 */
int
gnn_node_init (gnn_node           *node,
               const char         *type,
               gnn_node_f          f,
               gnn_node_df         dx,
               gnn_node_df         dw,
               gnn_node_destructor dest)
{
    assert (node != NULL);

    /* set fields */
    node->type  = strdup (type);
    node->n     = 0;
    node->m     = 0;
    node->super = NULL;
    node->nsub  = 0;
    node->sub   = NULL;
    node->f       = gnn_node_default_f;
    node->dx      = gnn_node_default_dx;
    node->dw      = gnn_node_default_dw;
    node->destroy = gnn_node_default_destructor;

    /* set parameters */
    node->pb = gnn_pbundle_new ();
    node->ph = NULL;

    /* set functions */
    if (f != NULL)
        node->f = f;

    if (dx != NULL)
        node->dx = dx;

    if (dx != NULL)
        node->dw = dw;

    if (dest != NULL)
        node->destroy = dest;

    return 0;
}

/**
 * @brief Set the node's sizes.
 * @ingroup gnn_node_ext_doc
 *
 * This function sets the node's sizes for its input, output and parameter
 * vector. It should be called after calling the \ref gnn_node_init (and
 * the \ref gnn_node_sub_install in case of a constructor node) function.
 *
 * @warning It is not allowed to call this function twice for the same node.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @param  n    The size of the node's input.
 * @param  m    The size of the node's output.
 * @param  l    The size of the node's parameter vector.
 * @return Returns 0 if succeeded.
 */
int
gnn_node_set_sizes (gnn_node *node, int n, int m, int l)
{
    assert (node != NULL);

    node->n = n;
    node->m = m;

    /* check if parameters aren't installed yet */
    if (node->ph != NULL)
        GSL_ERROR ("parameters are already installed", GSL_EINVAL);
        
    /* set parameters */
    node->ph = gnn_phandle_new (l);
    if (l > 0)
        gnn_pbundle_insert (node->pb, node->ph, 1);
    
    return 0;
}

/**
 * @brief Get local parameters.
 * @ingroup gnn_node_ext_doc
 *
 * This function returns a pointer to the node's own parameters.
 * The returning vector is the parameter vector itself and its values can
 * be freely changed. When finished, call \ref gnn_node_local_update.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @return Returns a pointer to the internal parameter vector \f$w\f$.
 */
gsl_vector *
gnn_node_local_get_w (gnn_node *node)
{
    assert (node != NULL);
    return gnn_phandle_get_w (node->ph);
}

/**
 * @brief Get local parameter gradients.
 * @ingroup gnn_node_ext_doc
 *
 * This function returns a pointer to the node's own parameters gradient
 * \f$\frac{\partial E}{\partial w}\f$.
 * The returning vector is the gradient itself and its values can
 * be freely changed. When finished, call \ref gnn_node_local_update.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @return Returns a pointer to the internal
 *         \f$\frac{\partial E}{\partial w}\f$ vector.
 */
gsl_vector *
gnn_node_local_get_dw (gnn_node *node)
{
    assert (node != NULL);
    return gnn_phandle_get_dw (node->ph);
}

/**
 * @brief Get local parameters frozen flags.
 * @ingroup gnn_node_ext_doc
 *
 * This function returns a pointer to the node's own parameters frozen flags.
 * The returning vector is the flags vector itself and its values can be freely
 * changed. When finished, call \ref gnn_node_local_update.
 *
 * The values should be binary: 0 means that the parameter is free, and
 * 1 (non-zero) means that the parameter is frozen (fixed).
 *
 * @param  node A pointer to an \ref gnn_node.
 * @return Returns a pointer to the internal flags vector.
 */
gsl_vector_int *
gnn_node_local_get_f (gnn_node *node)
{
    assert (node != NULL);
    return gnn_phandle_get_f (node->ph);
}

/**
 * @brief Get local parameters.
 * @ingroup gnn_node_ext_doc
 *
 * This function updates the local parameters and its changes. This function
 * should be called after any change in the parameters to make them effective.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @return Returns a pointer to the internal parameter vector \f$w\f$.
 */
int
gnn_node_local_update (gnn_node *node)
{
    assert (node != NULL);
    return gnn_phandle_update (node->ph);
}

/**
 * @brief Evaluates the output of the function recursively.
 * @ingroup gnn_node_ext_doc
 *
 * This function calls the installed \ref gnn_node::f function with the
 * appropiate arguments.
 *
 * This function should only be called from construction node's evaluation
 * functions. If you want to evaluate it from outside, you should call
 * \gnn_node_eval_f instead, which initiates the recursion parameters
 * appropiatelly.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @param  x    The input vector to be evaluated.
 * @param  y    A gsl_vector, where the result should be placed.
 * @return Returns 0 if suceeded.
 */
int
gnn_node_eval_f (gnn_node *node, const gsl_vector *x, gsl_vector *y)
{
    int status;

    assert (node != NULL);

    /* set pointer to last input */
    node->x = *x;
    
    /* call evaluation */
    status = node->f (node, &(node->x), gnn_phandle_get_w (node->ph), y);
    if (status)
        GSL_ERROR ("error computing y", GSL_ERANGE);

    return 0;
}

/**
 * @brief Evaluates \f$\frac{\partial E}{\partial x}\f$ recursively.
 * @ingroup gnn_node_ext_doc
 *
 * This function calls the installed \ref gnn_node::dx function with the
 * appropiate arguments.
 *
 * This function should only be called from construction node's evaluation
 * functions. If you want to evaluate it from outside, you should call
 * \gnn_node_eval_dx instead, which initiates the recursion parameters
 * appropiatelly.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @param  dx   A gsl_vector, where the result should be placed.
 * @return Returns 0 if suceeded.
 */
int
gnn_node_eval_dx (gnn_node *node, const gsl_vector *dy, gsl_vector *dx)
{
    int status;

    assert (node != NULL);

    /* set pointer to last input */
    node->dy = *dy;
    
    /* compute input gradient */
    status = node->dx (node,
                       &(node->x),
                       gnn_phandle_get_w (node->ph),
                       &(node->dy),
                       dx);
    if (status)
        GSL_ERROR ("error computing dw", GSL_ERANGE);

    return 0;
}

/**
 * @brief Evaluates \f$\frac{\partial E}{\partial w}\f$ recursively.
 * @ingroup gnn_node_ext_doc
 *
 * This function calls the installed \ref gnn_node::dw function with the
 * appropiate arguments.
 *
 * This function should only be called from construction node's evaluation
 * functions. If you want to evaluate it from outside, you should call
 * \gnn_node_eval_dw instead, which initiates the recursion parameters
 * appropiatelly.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @return Returns 0 if suceeded.
 */
int
gnn_node_eval_dw (gnn_node *node)
{
    int status;

    assert (node != NULL);

    /* if there aren't any free parameters,
       and the node is a leaf, return      */
    if (node->sub == NULL && gnn_phandle_get_free (node->ph) == 0)
        return 0;

    /* compute parameter gradient */
    status = node->dw (node,
                       &(node->x),
                       gnn_phandle_get_w (node->ph),
                       &(node->dy),
                       gnn_phandle_get_dw (node->ph));

    if (status)
        GSL_ERROR ("error computing dw", GSL_ERANGE);

    return 0;
}



/****************/
/* Subnodes API */
/****************/

/**
 * @brief The API for connecting and traversing trees of nodes.
 * @defgroup gnn_node_sub_doc gnn_node Subnodes API
 * @ingroup gnn_node_doc
 *
 * This API provides the functionality for connecting and traversing
 * \ref gnn_node trees.
 *
 * Every \ref 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 \ref 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 \ref 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 \ref 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 \ref gnn_node to be installed. Then, call
 * the \ref gnn_node_sub_install function, like in this example code:
 *
 * \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
       ...
 * \endcode
 *
 * Once installed, a subnode at the i-th index can be recovered by calling the
 * \ref gnn_node_sub_get_node_at function.
 *
 * When destroying a node with \ref gnn_node_destroy, its subnodes are
 * automatically uninstalled.
 */


/**
 * @brief Install subnodes.
 * @ingroup gnn_node_sub_doc
 *
 * This function installs the given nodes as subnodes.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @param  nsub The number of subnodes.
 * @param  ...  A list of subnodes to be installed.
 * @return Returns 0 if suceeded.
 */
int
gnn_node_sub_install_specific (gnn_node *node, int nsub, ...)
{
    va_list argptr;
    int     status;

    assert (node != NULL);

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

    return status;
}

/**
 * @brief Install subnodes.
 * @ingroup gnn_node_sub_doc
 *
 * This function installs the given nodes as subnodes.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @param  nsub The number of subnodes in the list.
 * @param  subs A va_list (C Standard Library) containing pointers to the
 *         subnodes to be installed.
 * @return Returns 0 if suceeded.
 */
int
gnn_node_sub_install (gnn_node *node, int nsub, va_list subs)
{
    int i;
    gnn_node *ptr;

    assert (node != NULL);
    assert (nsub > 0);

    /* create node array */
    node->sub = (gnn_node **) calloc (sizeof (gnn_node *), nsub);
    if (node->sub == NULL)
        GSL_ERROR ("failed to create subnode array", GSL_ENOMEM);

    /* set number of subnodes */
    node->nsub = nsub;

    /* fill subnode array */
    for (i=0; i<nsub; ++i)
    {
        /* get the node from the parameter list */
        node->sub[i] = (gnn_node *) va_arg (subs, gnn_node *);

        if (node->sub[i] == NULL)
            GSL_ERROR ("error installing subnodes", GSL_EINVAL);

        /* set the "super" pointer */
        node->sub[i]->super = node;

        /* merge parameter bundles */
        gnn_pbundle_join (node->pb, node->sub[i]->pb);
    }

    return 0;
}

/**
 * @brief Install the nodes in the node vector as subnodes.
 * @ingroup gnn_node_sub_doc
 *
 * This function installs the non-NULL nodes in the node vector as subnodes.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @param  vector A pointer to a \ref gnn_node_vector.
 * @return Returns 0 if suceeded.
 */
int
gnn_node_sub_install_node_vector (gnn_node *node, gnn_node_vector *vector)
{
    size_t i;
    size_t j;
    size_t count;
    gnn_node *ptr;

    assert (node != NULL);

    /* count the number of non-null nodes */
    count = gnn_node_vector_count_nodes (vector);

    if (count < 1)
        GSL_ERROR ("the given vector doesn't contain any valid gnn_node",
                   GSL_EINVAL);

    /* create node array */
    node->sub = (gnn_node **) calloc (sizeof (gnn_node *), count);
    if (node->sub == NULL)
        GSL_ERROR ("failed to create subnode array", GSL_ENOMEM);

    /* set number of subnodes */
    node->nsub = count;

    /* fill subnode array */
    j = 0;
    for (i=0; i<vector->size; ++i)
    {
        /* check if there is a valid node */
        if (gnn_node_vector_get (vector, i) == NULL)
            continue;

        /* get node and install */
        node->sub[j] = gnn_node_vector_get (vector, i);

        /* set the "super" pointer */
        node->sub[j]->super = node;

        /* merge parameter bundles */
        gnn_pbundle_join (node->pb, node->sub[j]->pb);
        
        /* advance to next subnode element */
        j++;
    }

    return 0;
}


/**
 * @brief Get the number of subnodes.
 * @ingroup gnn_node_sub_doc
 *
 * This function returns the number of direct subnodes of the node.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @return Returns the number of subnodes.
 */
int
gnn_node_sub_get_number (gnn_node *node)
{
    assert (node != NULL);
    return node->nsub;
}

/**
 * @brief Get's the node's i-th subnode.
 * @ingroup gnn_node_sub_doc
 *
 * This function returns a pointer to the i-th subnode.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @param  i The index of the subnode to be retrieved.
 * @return The pointer to the i-th subnode or NULL if failed.
 */
gnn_node *
gnn_node_sub_get_node_at (gnn_node *node, int i)
{
    assert (node != NULL);
    assert (node->sub != NULL);
    assert (0 <= i && i < node->nsub);

    return node->sub[i];
}

/**
 * @brief Get all subnodes of a given type.
 * @ingroup gnn_node_sub_doc
 *
 * This function searches the whole node three for nodes of the given type,
 * and returns a parameter bundle of all their parameters.
 *
 * @param  node A pointer to an \ref gnn_node.
 * @param  type A string containing the type of the subnodes to be retrieved.
 * @return A \ref gnn_pbundle.
 */
gnn_pbundle *
gnn_node_sub_search_params (gnn_node *node, const char *type)
{
    gnn_pbundle *pb;
    
    assert (node != NULL);

    /* create new parameter bundle */
    pb = gnn_pbundle_new ();
    
    /* call recursive function */
    gnn_node_sub_search_params_recurse (node, type, pb);

    return pb;
}

---