---

gnn_parallel.c

Go to the documentation of this file.

/***************************************************************************
 *  @file gnn_parallel.h
 *  @brief Parallel Layer.
 *
 *  @date   : 10-08-03 18:59, 22-08-03 00:19
 *  @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.
 */

/**
 * @defgroup gnn_parallel_doc gnn_parallel : Parallel Node Constructor.
 * @ingroup gnn_constructor_doc
 *
 * @todo Optimize this node type
 *
 * gnn_parallel is a constructor node for implementing parallel computing
 * schemes. Given the \f$N\f$ functions \f$g_1, \ldots, g_N\f$ with
 * input sizes \f$n_1, \ldots, n_N\f$ and output sizes \f$ m_1, \ldots, m_N \f$,
 * it computes the function
 * \f$ F: \mathbf{R}^{(n_1 + \cdots + n_N)}
 *       \rightarrow \mathbf{R}^{(m_1 + \cdots + m_N)}\f$ given by
 * \f[
 *     F(X) = [g_1(X_1) g_2(X_2) \ldots g_N(X_N)]
 *          = [Y_1 Y_2 \ldots Y_N]
 * \f]
 * where \f$ \forall i=1,\ldots,N, Y_i = g(X_i) \f$, in this order.
 */


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

#include "gnn_parallel.h"
#include <assert.h>



/******************************************/
/* Static Declaration                     */
/******************************************/

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

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

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

static void
gnn_parallel_destroy (gnn_node *node);



/******************************************/
/* Static Implementation                  */
/******************************************/

/**
 * @brief Computes the output.
 * @ingroup gnn_parallel_doc
 *
 * This functions computes the parallel function.
 *
 * @param  node A pointer to a \ref gnn_parallel node.
 * @param x    The input vector \f$x\f$.
 * @param w    The current parameter vector \f$w\f$.
 * @param y    An output vector \f$y\f$ where the result should be stored.
 * @return 0 if succeeded.
 */
static int
gnn_parallel_f (gnn_node *node,
                const gsl_vector *x,
                const gsl_vector *w,
                gsl_vector *y)
{
    gnn_parallel *pnode;
    int size;
    int i;

    /* get view as parallel node */
    pnode = (gnn_parallel *) node;

    /* retrieve size */
    size = gnn_node_sub_get_number (node);

    /* foreach of the subnodes, compute output */
    for (i=0; i<size; ++i)
    {
        int in_offset;
        int in_length;
        int out_offset;
        int out_length;
        gsl_vector_view sx;
        gsl_vector_view sy;
        gnn_node *snode;

        /* get subnode */
        snode = gnn_node_sub_get_node_at (node, i);

        /* get offsets and lengths */
        in_offset  = pnode->in_off[i];
        in_length  = pnode->in_size[i];
        out_offset = pnode->out_off[i];
        out_length = pnode->out_size[i];

        /* get the corresponding views */
        sx = gsl_vector_subvector ((gsl_vector *) x, in_offset, in_length);
        sy = gsl_vector_subvector (y, out_offset, out_length);
        
        /* evaluate subnode */
        gnn_node_eval_f (snode, &(sx.vector), &(sy.vector));
    }

    return 0;
}


/**
 * @brief Computes \f$ \frac{\partial E}{\partial x} \f$.
 * @ingroup gnn_parallel_doc
 *
 * This functions computes the input gradient of the parallel node.
 * Given \f$ \frac{\partial E}{\partial y} =
 * [ \frac{\partial E}{\partial y_1}
 *   \frac{\partial E}{\partial y_2} \ldots
 *   \frac{\partial E}{\partial y_N} ] \f$
 * it computes
 * \f[ \frac{\partial E}{\partial x} =
 *     [ \frac{\partial E}{\partial x_1}
 *       \frac{\partial E}{\partial x_2} \ldots
 *       \frac{\partial E}{\partial x_N} ]
 * \f]
 * where \f$ \forall i=1,\ldots,N;  \frac{\partial E}{\partial x_i} \f$ is
 * the gradient with respect of its inputs of the \f$i\f$-th function
 * \f$ g_i \f$.
 *
 * @param  node A pointer to a \ref gnn_parallel node.
 * @param x    The input vector \f$x\f$.
 * @param w    The current parameter vector \f$w\f$.
 * @param dy   The error-backpropagation vector
 *             \f$\frac{\partial E}{\partial y}\f$
 * @param dx   An output vector where the result
 *             \f$\frac{\partial E}{\partial x}\f$ should be stored.
 * @return 0 if suceeded.
 */
static int
gnn_parallel_dx (gnn_node *node,
                 const gsl_vector *x,
                 const gsl_vector *w,
                 const gsl_vector *dy,
                 gsl_vector *dx)
{
    gnn_parallel *pnode;
    int size;
    int i;

    /* get view as parallel node */
    pnode = (gnn_parallel *) node;

    /* retrieve size */
    size = gnn_node_sub_get_number (node);

    /* foreach of the subnodes, compute input gradient */
    for (i=0; i<size; ++i)
    {
        int in_offset;
        int in_length;
        int out_offset;
        int out_length;
        gsl_vector_view sdx;
        gsl_vector_view sdy;
        gnn_node *snode;

        /* get subnode */
        snode = gnn_node_sub_get_node_at (node, i);

        /* get offsets and lengths */
        in_offset  = pnode->in_off[i];
        in_length  = pnode->in_size[i];
        out_offset = pnode->out_off[i];
        out_length = pnode->out_size[i];

        /* get the corresponding views */
        sdy = gsl_vector_subvector ((gsl_vector *) dy, out_offset, out_length);
        sdx = gsl_vector_subvector (dx, in_offset, in_length);

        /* evaluate subnode */
        gnn_node_eval_dx (snode, &(sdy.vector), &(sdx.vector));
    }

    return 0;
}

/**
 * @brief Computes \f$ \frac{\partial E}{\partial w} \f$.
 * @ingroup gnn_parallel_doc
 *
 * This functions computes the parameter gradient of the parallel node.
 * Given \f$ \frac{\partial E}{\partial y} =
 * [ \frac{\partial E}{\partial y_1}
 *   \frac{\partial E}{\partial y_2} \ldots
 *   \frac{\partial E}{\partial y_N} ] \f$
 * it computes
 * \f[ \frac{\partial E}{\partial w} =
 *     [ \frac{\partial E}{\partial w_1}
 *       \frac{\partial E}{\partial w_2} \ldots
 *       \frac{\partial E}{\partial w_N} ]
 * \f]
 * where \f$ \forall i=1,\ldots,N;  \frac{\partial E}{\partial w_i} \f$ is
 * the gradient with respect of its parameters of the \f$i\f$-th function
 * \f$ g_i \f$.
 *
 * @param node A pointer to a \ref gnn_parallel node.
 * @param x    The input vector \f$x\f$.
 * @param w    The current parameter vector \f$w\f$.
 * @param dy   The error-backpropagation vector
 *             \f$\frac{\partial E}{\partial y}\f$
 * @param dw   Not used, since the stack hasn't any local parameters.
 * @return 0 if succeeded.
 */
static int
gnn_parallel_dw (gnn_node *node,
                 const gsl_vector *x,
                 const gsl_vector *w,
                 const gsl_vector *dy,
                 gsl_vector *dw)
{
    int size;
    int i;

    /* retrieve size */
    size = gnn_node_sub_get_number (node);

    /* foreach of the subnodes, compute dw */
    for (i=0; i<size; ++i)
    {
        gnn_node *snode;

        /* get sublayer */
        snode = gnn_node_sub_get_node_at (node, i);

        /* evaluate sublayer and copy result */
        gnn_node_eval_dw (snode);
    }

    return 0;
}

/**
 * @brief Frees the \ref gnn_parallel specific data.
 * @ingroup gnn_parallel_doc
 *
 * This function (the \ref gnn_parallel destructor) frees the 4 auxiliary
 * arrays allocated for the \ref gnn_parallel node.
 *
 * @param  node A pointer to a \ref gnn_parallel node.
 */
static void
gnn_parallel_destroy (gnn_node *node)
{
    gnn_parallel *pnode;
    
    assert (node != NULL);
    
    /* get view as parallel node */
    pnode = (gnn_parallel *) node;
    
    /* free the info arrays if any */
    if (pnode->in_off   != NULL)
        free (pnode->in_off);
    if (pnode->in_size  != NULL)
        free (pnode->in_size);
    if (pnode->out_off  != NULL)
        free (pnode->out_off);
    if (pnode->out_size != NULL)
        free (pnode->out_size);
}




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

/**
 * @brief Creates a \ref gnn_parallel node.
 * @ingroup gnn_parallel_doc
 *
 * This function creates a node of the \ref gnn_parallel type. Its inputs
 * and outputs are the concatenation of its subnode's inputs and outputs.
 *
 * Example:
 * \code
 * gnn_node *parallel, *node1, *node2, *node3;
 *
 * // build the node 1 to 3
 * ...
 *
 * // build the parallel node
 * parallel = gnn_parallel_new (3, node1, node2, node3);
 * \endcode
 *
 * @param size The number of subnodes.
 * @param ...  A list of pointers to the subnodes.
 * @return A pointer to a new \ref gnn_parallel node.
 */
gnn_node *
gnn_parallel_new (size_t size, ...)
{
    size_t  i;
    va_list args;
    gnn_node        *p;
    gnn_node_vector *v;
    
    assert (size > 0);
    
    /* create node vector */
    v = gnn_node_vector_new (size);
    if (v == NULL)
    {
        GSL_ERROR_VAL ("couldn't allocate node vector for parallel node",
                       GSL_ENOMEM, NULL);
    }

    /* prepare node array */
    va_start (args, size);
    for (i=0; i<size; ++i)
    {
        gnn_node *n;
        n = (gnn_node *) va_arg (args, gnn_node *);
        gnn_node_vector_set (v, i, n);
    }
    va_end (args);

    /* call parallel node builder */
    p = gnn_parallel_new_with_node_vector (v);

    /* free vector */
    gnn_node_vector_free (v);
    
    return p;
}

/**
 * @brief Creates a \ref gnn_parallel node with a given node vector.
 * @ingroup gnn_parallel_doc
 *
 * This function creates a node of the \ref gnn_parallel type. Its inputs
 * and outputs are the concatenation of its subnode's inputs and outputs.
 *
 * Example:
 * \code
 * gnn_node *parallel;
 * gnn_node_vector *vector;
 *
 * // build the node vector
 * vector = gnn_node_vector_new (3);
 *
 * // build the nodes vector[0], vector[1] and vector[2]
 * ...
 *
 * // build the stack
 * parallel = gnn_parallel_new_with_node_vector (vector);
 * \endcode
 *
 * @param v A pointer to a \ref gnn_node_vector.
 * @return A pointer to a new \ref gnn_parallel node.
 */
gnn_node *
gnn_parallel_new_with_node_vector (gnn_node_vector *v)
{
    int i;
    int status;
    size_t size;
    size_t input_size;
    size_t output_size;
    gnn_node     *node;
    gnn_parallel *pnode;

    assert (v != NULL);

    /* get size */
    size = gnn_node_vector_count_nodes (v);

    /* allocate parallel node */
    node = (gnn_node *) malloc (sizeof (gnn_parallel));
    if (node == NULL)
    {
        GSL_ERROR_VAL ("could not allocate memory for gnn_parallel",
                       GSL_ENOMEM, NULL);
    }

    /* initialize parallel node */
    status = gnn_node_init (node,
                            "gnn_parallel",
                            gnn_parallel_f,
                            gnn_parallel_dx,
                            gnn_parallel_dw,
                            gnn_parallel_destroy);
    if (status)
    {
        free (node);
        GSL_ERROR_VAL ("could not initialize gnn_parallel node",
                       GSL_EFAILED, NULL);
    }

    /* store layers */
    status = gnn_node_sub_install_node_vector (node, v);
    if (status)
    {
        gnn_node_destroy (node);
        GSL_ERROR_VAL ("couldn't install subnodes for gnn_parallel",
                       GSL_EINVAL, NULL);
    }

    /* get view as a parallel node */
    pnode = (gnn_parallel *) node;

    /* alloc arrays for holding subnode's info */
    pnode->in_off   = (size_t *) malloc (sizeof (size_t) * size);
    pnode->in_size  = (size_t *) malloc (sizeof (size_t) * size);
    pnode->out_off  = (size_t *) malloc (sizeof (size_t) * size);
    pnode->out_size = (size_t *) malloc (sizeof (size_t) * size);

    if (   pnode->in_off   == NULL
        || pnode->in_size  == NULL
        || pnode->out_off  == NULL
        || pnode->out_size == NULL )
    {
        gnn_node_destroy (node);
        GSL_ERROR_VAL ("could not allocate memory for gnn_parallel info arrays",
                       GSL_ENOMEM, NULL);
    }

    /* compute input and output size and build info arrays */
    input_size    = 0;
    output_size   = 0;
    for (i=0; i<size; ++i)
    {
        size_t inlen;
        size_t outlen;

        gnn_node *subnode;

        subnode = gnn_node_sub_get_node_at (node, i);

        inlen  = gnn_node_input_get_size (subnode);
        outlen = gnn_node_output_get_size (subnode);

        pnode->in_off[i]   = input_size;
        pnode->in_size[i]  = inlen;
        pnode->out_off[i]  = output_size;
        pnode->out_size[i] = outlen;

        input_size  += inlen;
        output_size += outlen;
    }

    /* resize the parallel node's input and output */
    gnn_node_set_sizes (node, input_size, output_size, 0);

    return node;
}


/**
 * @brief Gets the offset of the i-th subnode's input.
 * @ingroup gnn_parallel_doc
 *
 * @param  node A pointer to a \ref gnn_parallel node.
 * @param  i    The index.
 * @return The offset.
 */
int
gnn_parallel_get_input_offset (gnn_node *node, int i)
{
    int sub_size;
    gnn_parallel *pnode;

    pnode    = (gnn_parallel *) node;
    sub_size = gnn_node_sub_get_number (node);
    if ( (0 <= i) && (i < sub_size) )
        return pnode->in_off[i];
    else
        GSL_ERROR ("index of parallel layer out of bounds", GSL_EINVAL);
}

/**
 * @brief Gets the length of the i-th subnode's input.
 * @ingroup gnn_parallel_doc
 *
 * @param  node A pointer to a \ref gnn_parallel node.
 * @param  i    The index.
 * @return The length.
 */
int
gnn_parallel_get_input_length (gnn_node *node, int i)
{
    int sub_size;
    gnn_parallel *pnode;

    pnode    = (gnn_parallel *) node;
    sub_size = gnn_node_sub_get_number (node);
    if ( (0 <= i) && (i < sub_size) )
        return pnode->in_size[i];
    else
        GSL_ERROR ("index of parallel layer out of bounds", GSL_EINVAL);
}

/**
 * @brief Gets the offset of the i-th subnode's output.
 * @ingroup gnn_parallel_doc
 *
 * @param  node A pointer to a \ref gnn_parallel node.
 * @param  i    The index.
 * @return The offset.
 */
int
gnn_parallel_get_output_offset (gnn_node *node, int i)
{
    int sub_size;
    gnn_parallel *pnode;

    pnode    = (gnn_parallel *) node;
    sub_size = gnn_node_sub_get_number (node);
    if ( (0 <= i) && (i < sub_size) )
        return pnode->out_off[i];
    else
        GSL_ERROR ("index of parallel layer out of bounds", GSL_EINVAL);
}

/**
 * @brief Gets the length of the i-th subnode's output.
 * @ingroup gnn_parallel_doc
 *
 * @param  node A pointer to a \ref gnn_parallel node.
 * @param  i    The index.
 * @return The offset.
 */
int
gnn_parallel_get_output_length (gnn_node *node, int i)
{
    int sub_size;
    gnn_parallel *pnode;

    pnode    = (gnn_parallel *) node;
    sub_size = gnn_node_sub_get_number (node);
    if ( (0 <= i) && (i < sub_size) )
        return pnode->out_size[i];
    else
        GSL_ERROR ("index of parallel layer out of bounds", GSL_EINVAL);
}

---