---

gnn_serial.c

Go to the documentation of this file.

/***************************************************************************
 *  @file gnn_serial.c
 *  @brief gnn_serial Function Stacking Layer.
 *
 *  @date   : 06-08-03 21:51
 *  @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 A constructor node for node stacking.
 * @defgroup gnn_serial_doc gnn_serial : Serial Constructor for Function Composition.
 * @ingroup  gnn_constructor_doc
 *
 * This node allows to stack nodes one on another. The resulting function
 * is the composition of the node's subfunctions. That is, given \f$N\f$
 * functions \f$g_1, g_2, g_3, \ldots, g_N\f$ in this order, the stack node
 * forms the function
 * \f[ Y = F(X) = g_N \circ g_{N-1} \circ \ldots \circ g_1 (X) \f]
 *
 * A new stack node can be built using the \ref gnn_serial_new function.
 */

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

#include <stdarg.h>
#include "gnn_serial.h"



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

/**
 * @brief Internal buffer structure.
 * @ingroup gnn_serial_doc
 *
 * This structure stores the buffers needed for saving the intermediate results
 * between the subfunction's evaluations.
 */
typedef struct _stack_buf
{
    gsl_vector *xy;    /**< Stores intermediate function evaluation       */
    gsl_vector *dydx;  /**< Stores intermediate
                            \f$\frac{\partial E}{\partial x}\f$ gradients */
} stack_buffer;

/**
 * @brief \ref gnn_serial structure.
 * @ingroup gnn_serial_doc
 *
 * This is the real structure for a \ref gnn_serial node. It needs to store
 * additional information for managing the interfunction activity.
 */
typedef struct _gnn_serial
{
    gnn_node      node;    /**< The subyacent \ref gnn_node         */
    stack_buffer *buffers; /**< The buffers for intermediate values */
} gnn_serial;



static int
stack_buffer_init (stack_buffer *sb, size_t size);

static int
stack_buffer_clear (stack_buffer *sb);

static int
stack_buffer_finalize (stack_buffer *sb);

static int
gnn_serial_make_buffers (gnn_node *node);

static int
gnn_serial_destroy_buffers (gnn_node *node);



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

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

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

static void
gnn_serial_destroy (gnn_node *node);


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

/**
 * @brief Initializes a stack buffer.
 * @ingroup gnn_serial_doc
 *
 * This function initializes a buffer of the given size.
 *
 * @param  sb   A pointer to a \ref stack_buffer structure.
 * @param  size The size of the buffers.
 * @return 0 if suceeded.
 */
static int
stack_buffer_init (stack_buffer *sb, size_t size)
{
    assert (sb != NULL);
    assert (size >= 0);
    
    /* set fields */
    if (size > 0)
    {
        sb->xy   = gsl_vector_alloc (size);
        sb->dydx = gsl_vector_alloc (size);
        if (sb->xy == NULL || sb->dydx == NULL)
        {
            stack_buffer_finalize (sb);
            GSL_ERROR ("couldn't initialize stack buffer", GSL_ENOMEM);
        }
    }
    return 0;
}

/**
 * @brief Clears a stack buffer.
 * @ingroup gnn_serial_doc
 *
 * This function resets the buffers to zero.
 *
 * @param  sb   A pointer to a \ref stack_buffer structure.
 * @return 0 if suceeded.
 */
static int
stack_buffer_clear (stack_buffer *sb)
{
    assert (sb != NULL);

    /* clear buffers */
    if (sb->xy != NULL && sb->dydx != NULL)
    {
        gsl_vector_set_zero (sb->xy);
        gsl_vector_set_zero (sb->dydx);
    }
    return 0;
}

/**
 * @brief Finalizes a stack buffer.
 * @ingroup gnn_serial_doc
 *
 * This function finalizes a \ref stack_buffer, by freeing the memory
 * associated to its buffer.
 *
 * @param  sb   A pointer to a \ref stack_buffer structure.
 * @return 0 if suceeded.
 */
static int
stack_buffer_finalize (stack_buffer *sb)
{
    assert (sb != NULL);
    
    /* deallocate vector buffer if any */
    if (sb->xy != NULL)
        gsl_vector_free (sb->xy);
    if (sb->dydx != NULL)
        gsl_vector_free (sb->dydx);
    
    return 0;
}

/**
 * @brief Builds the buffers for a given \ref gnn_serial node.
 * @ingroup gnn_serial_doc
 *
 * This function takes a \ref gnn_serial node as argument, and builds the
 * corresponding buffers for the installed subnodes.
 *
 * @param  node A pointer to a \ref gnn_serial structure.
 * @return 0 if suceeded.
 */
static int
gnn_serial_make_buffers (gnn_node *node)
{
    int i;
    int size;
    gnn_serial *stack;
    gnn_node  *pre;
    gnn_node  *post;
    
    assert (node != NULL);
    
    /* get number of subnodes */
    size = gnn_node_sub_get_number (node);
    if (size < 2)
        return 0;
    
    /* cast to stack */
    stack = (gnn_serial *) node;
    
    /* allocate space for stack buffer */
    stack->buffers = (stack_buffer *) malloc (sizeof (stack_buffer) * (size-1));
    if (stack->buffers == NULL)
        GSL_ERROR ("couldn't allocate stack buffers", GSL_ENOMEM);

    /* fill buffers */
    post = gnn_node_sub_get_node_at (node, 0);
    for (i=0; i<size-1; ++i)
    {
        int m, n, status;
        
        pre = post;
        post = gnn_node_sub_get_node_at (node, i + 1);
        
        /* check sizes */
        m = gnn_node_output_get_size (pre);
        n = gnn_node_input_get_size (post);
        if (m != n)
        {
            gnn_serial_destroy_buffers (node);
            GSL_ERROR ("the size of two consecutive nodes should match",
                       GSL_EINVAL);
        }
        
        /* make buffer */
        status = stack_buffer_init (&(stack->buffers[i]), n);
        if (status)
        {
            gnn_serial_destroy_buffers (node);
            GSL_ERROR ("couldn't create stack buffers", GSL_ENOMEM);
        }
    }
    
    return 0;
}

/**
 * @brief Destroys a \ref gnn_serial node's stack buffers.
 * @ingroup gnn_serial_doc
 *
 * This function destroys the buffers for the current \ref gnn_serial node.
 *
 * @param  node A pointer to a \ref gnn_serial structure.
 * @return 0 if suceeded.
 */
static int
gnn_serial_destroy_buffers (gnn_node *node)
{
    int i;
    int size;
    gnn_serial *stack;

    assert (node != NULL);

    /* get number of subnodes */
    size = gnn_node_sub_get_number (node);
    if (size < 2)
        return 0;

    /* cast to stack */
    stack = (gnn_serial *) node;

    /* destroy buffers */
    for (i=0; i<size-1; ++i)
    {
        stack_buffer_finalize (&(stack->buffers[i]));
    }
    
    return 0;
}

/**
 * @brief Evaluate a stack node.
 * @ingroup gnn_serial_doc
 *
 * This function computes the result from the stack node. If its \f$N\f$
 * subnodes implement the functions \f$g_1, g_2, \ldots, g_N\f$ then
 * the result is given by
 * \f[ Y = g_N \circ \ldots \circ g_2 \circ g_1 (X) \f]
 *
 * @param node A stack 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_serial_f (gnn_node *node,
             const gsl_vector *x,
             const gsl_vector *w,
             gsl_vector *y)
{
    int i;
    int size;
    gnn_serial  *stack;
    
    const gsl_vector *xptr;
    gnn_node         *subnode;
    gsl_vector       *yptr;
    
    assert (node != NULL);

    /* initialize stack evaluation */
    stack   = (gnn_serial *) node;
    size    = gnn_node_sub_get_number (node);
    xptr    = x;
    subnode = gnn_node_sub_get_node_at (node, 0);

    /* traverse stack evaluation */
    for (i=0; i<size-1; ++i)
    {
        /* clear buffer */
        stack_buffer_clear (&(stack->buffers[i]));

        /* set output buffer */
        yptr = stack->buffers[i].xy;

        /* evaluate */
        gnn_node_eval_f (subnode, xptr, yptr);

        /* move pointers for next iteration */
        xptr = yptr;
        subnode = gnn_node_sub_get_node_at (node, i+1);
    }

    /* last evaluation */
    yptr = y;
    gnn_node_eval_f (subnode, xptr, yptr);

    return 0;
}

/**
 * @brief Computes \f$\frac{\partial E}{\partial x}\f$ for the doc.
 * @ingroup gnn_serial_doc
 *
 * This function computes the gradient \f$\frac{\partial E}{\partial x}\f$
 * as:
 * \f[ \frac{\partial E}{\partial x}
 *     = \frac{\partial E}{\partial x_N}
 *       \circ \frac{\partial E}{\partial x_{N-1}} \ldots
 *       \circ \frac{\partial E}{\partial x_1}
 *       (\frac{\partial E}{\partial y})
 * \f]
 * where \f$x_1, \ldots, x_N\f$ where the \f$N\f$ input vectors involved
 * in the subnode's functions \f$g_1, \ldots, g_N\f$.
 *
 * @param node A stack 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_serial_dx (gnn_node *node,
               const gsl_vector *x,
               const gsl_vector *w,
               const gsl_vector *dy,
               gsl_vector *dx)
{
    int i;
    int size;
    gnn_serial  *stack;

    const gsl_vector *dyptr;
    gnn_node         *subnode;
    gsl_vector       *dxptr;

    assert (node != NULL);

    /* initialize stack evaluation */
    stack   = (gnn_serial *) node;
    size    = gnn_node_sub_get_number (node);
    dyptr   = dy;
    subnode = gnn_node_sub_get_node_at (node, size-1);

    /* traverse stack evaluation */
    for (i=size-1; i>0; --i)
    {
        /* set dx buffer */
        dxptr = stack->buffers[i-1].dydx;

        /* evaluate */
        gnn_node_eval_dx (subnode, dyptr, dxptr);

        /* move pointers for next iteration */
        dyptr = dxptr;
        subnode = gnn_node_sub_get_node_at (node, i-1);
    }

    /* last evaluation */
    dxptr = dx;
    gnn_node_eval_dx (subnode, dyptr, dxptr);

    return 0;
}

/**
 * @brief Computes \f$\frac{\partial E}{\partial w}\f$ for the node.
 * @ingroup gnn_serial_doc
 *
 * This function triggers the computation of the subnode's gradients
 * \f$\frac{\partial E}{\partial w_1}, \frac{\partial E}{\partial w_2},
 * \ldots, \frac{\partial E}{\partial w_N} \f$ involved in the \f$N \f$
 * sublayers \f$g_1, \ldots, g_N\f$.
 *
 * @param node A stack 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_serial_dw (gnn_node *node,
               const gsl_vector *x,
               const gsl_vector *w,
               const gsl_vector *dy,
               gsl_vector *dw)
{
    int i;
    int size;
    
    assert (node != NULL);

    /* initialize stack evaluation */
    size = gnn_node_sub_get_number (node);

    /* traverse stack evaluation */
    for (i=0; i<size; ++i)
    {
        gnn_node *subnode;

        /* evaluate */
        subnode = gnn_node_sub_get_node_at (node, i);
        gnn_node_eval_dw (subnode);
    }

    return 0;
}

/**
 * @brief \ref gnn_serial destructor.
 * @ingroup gnn_serial_doc
 *
 * This function destroys the \ref gnn_serial's specific data.
 *
 * @param node A pointer to a \ref gnn_serial node.
 */
static void
gnn_serial_destroy (gnn_node *node)
{
    assert (node != NULL);
    
    /* free buffers */
    gnn_serial_destroy_buffers (node);
}



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

/**
 * @brief Build a node stack.
 * @ingroup gnn_serial_doc
 *
 * This function builds a new gnn_serial node. The node computes
 * the function \f$ Y = g_N \circ \ldots \circ g_1 (X)\f$, where 
 * \f$g_1, \ldots, g_N\f$ are the functions implemented by the subnodes
 * given as arguments, in the same order.
 *
 * The input and output sizes should match on each other, so that
 * the output size of a preceeding node must be the same as the input size
 * of the following node.
 *
 * Example:
 * \code
 * gnn_node *stack, *node1, *node2, *node3;
 *
 * // build the nodes 1 to 3
 * ...
 *
 * // build the stack
 * stack = gnn_serial_new (3, node1, node2, node3);
 * \endcode
 *
 * @param size The number of subnodes.
 * @param ...  The list of subnodes.
 * @return A new stack node.
 */
gnn_node *
gnn_serial_new (int size, ...)
{
    size_t  i;
    va_list args;
    gnn_node        *s;
    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 gnn_serial 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 stack node builder */
    s = gnn_serial_new_with_node_vector (v);

    /* free vector */
    gnn_node_vector_free (v);

    return s;
}

/**
 * @brief Build a node stack with a given node vector.
 * @ingroup gnn_serial_doc
 *
 * This function builds a new gnn_serial node. The node computes
 * the function \f$ Y = g_N \circ \ldots \circ g_1 (X)\f$, where
 * \f$g_1, \ldots, g_N\f$ are the functions implemented by the subnodes
 * given as arguments, in the same order.
 *
 * The input and output sizes should match on each other, so that
 * the output size of a preceeding node must be the same as the input size
 * of the following node.
 *
 * Example:
 * \code
 * gnn_node *stack;
 * 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
 * stack = gnn_serial_new_with_node_vector (vector);
 * \endcode
 *
 * @todo  Automatic divergence-convergence insertion.
 * @param v A pointer to a \ref gnn_node_vector.
 * @return A new stack node.
 */
gnn_node *
gnn_serial_new_with_node_vector (gnn_node_vector *v)
{
    int       status;
    size_t    n;
    size_t    m;
    size_t    size;
    gnn_node *node;

    assert (v != NULL);

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

    /* allocate stack node */
    node = (gnn_node *) malloc (sizeof (gnn_serial));
    if (node == NULL)
        GSL_ERROR_VAL ("couldn't allocate memory for gnn_serial node",
                       GSL_EINVAL, NULL);;

    /* initialize stack layer */
    status = gnn_node_init (node,
                            "gnn_serial",
                            gnn_serial_f,
                            gnn_serial_dx,
                            gnn_serial_dw,
                            gnn_serial_destroy);
    if (status)
    {
        free (node);
        GSL_ERROR_VAL ("couldn't init gnn_serial", GSL_ENOMEM, 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_serial",
                       GSL_EINVAL, NULL);
    }

    /* set sizes */
    n = gnn_node_input_get_size  (gnn_node_sub_get_node_at (node, 0));
    m = gnn_node_output_get_size (gnn_node_sub_get_node_at (node, size-1));

    status = gnn_node_set_sizes (node, n, m, 0);
    if (status)
    {
        gnn_node_destroy (node);
        GSL_ERROR_VAL ("couldn't set sizes for gnn_serial", GSL_EINVAL, NULL);
    }

    /* install buffers */
    status = gnn_serial_make_buffers (node);
    if (status)
    {
        gnn_node_destroy (node);
        GSL_ERROR_VAL ("couldn't install buffers", GSL_EINVAL, NULL);
    }

    return node;
}

/**
 * @brief Get the i-th subnode.
 * @ingroup gnn_serial_doc
 *
 * This function returns a pointer to the stack's i-th node.
 *
 * @param node A stack node.
 * @param i    The node's index (should be within [0, size-1]).
 * @return A pointer to the i-th node or NULL if failed.
 */
gnn_node *
gnn_serial_get_node (gnn_node *node, int i)
{
    return gnn_node_sub_get_node_at (node, i);
}

/**
 * @brief Gets the number of nodes that the stack is build of.
 * @ingroup gnn_serial_doc
 *
 * @param  node A stack node.
 * @return Size of the stack.
 */
int
gnn_serial_get_size (gnn_node *node)
{
    return gnn_node_sub_get_number (node);
}

---