---

gnn_convergence.c

Go to the documentation of this file.

/***************************************************************************
 *  @file gnn_convergence.c
 *  @brief gnn_convergence Implementation.
 *
 *  @date   : 28-09-03 13:41
 *  @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_convergence_doc gnn_convergence : Input Convergence.
 * @ingroup gnn_atomic_doc
 *
 * The \ref gnn_convergence node is a special node that takes a big input
 * vector and slices it into mini-vectors that fit into the output. This
 * can be viewed a if the input where in reality a concatenation of subvectors
 * of the same size.
 *
 * The function implemented by this node is given by:
 *
 * \f[ y_j =
 * \frac{1}{S} \left ( x_j + x_{m+j} + x_{2m+j} + \ldots + x_{(S-1)m+j} \right )
 *         = \frac{1}{S} \sum_{k=0}^{S-1} x_{km+j}
 * \f]
 *
 * In other words, it slices the input vector \f$x\f$ into several subvectors
 * of size \f$m \times 1\f$ and sums them up, divided by the total amount
 * of resulting pieces \f$S\f$. Remember that \f$m\f$ is the output size.
 *
 * If the input vector's
 * size isn't a multiple of the output vector's size,
 * that is, if \f$n\f$ can't be written as \f$km\f$, then the last vector slice
 * will consider only the remaining terms, e.g.
 * if \f$x=[x_0, \ldots, x_5]^T\f$ and \f$y\f$ is of size
 * \f$4 \times 1\f$ then
 *
 * \f[ y = 1/2 \left [ \begin{array}{c}
 *                     (x_0 + x_4) \\
 *                     (x_1 + x_5) \\
 *                      x_2 \\
 *                      x_3 \\
 *         \end{array} \right ]
 * \f]
 *
 * Schematically, this idea can be depicted as
 *
 * <img src="images/gnn_convergence1.png">
 *
 * The function's gradient is:
 * \f[ \frac{\partial E}{\partial x_i}
 *     = S \frac{\partial E}{\partial x_{km+j}}
 *     = S \frac{\partial E}{\partial y_j}
 * \f]
 *
 *
 */


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

#include "gnn_convergence.h"



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

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

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

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

static void
gnn_convergence_destroy (gnn_node *node);



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

/**
 * @brief Computes the output.
 * @ingroup gnn_convergence_doc
 *
 * @param   node A pointer to the \ref gnn_convergence node.
 * @param x The input vector \f$x\f$.
 * @param w The parameter vector \f$w\f$.
 * @param y The output buffer vector \f$y\f$.
 * @return Returns 0 on success.
 */
static int
gnn_convergence_f (gnn_node *node,
                   const gsl_vector *x,
                   const gsl_vector *w,
                   gsl_vector *y)
{
    size_t n;
    size_t m;
    size_t k;
    gnn_convergence *cnode;

    /* get views */
    cnode = (gnn_convergence *) node;

    /* get input and output size */
    n = gnn_node_input_get_size (node);
    m = gnn_node_output_get_size (node);

    /* evaluate */
    gsl_vector_set_zero (y);
    for (k=0; k<n; ++k)
    {
        size_t j;
        double yj;
        
        j   = k % m;
        yj  = gsl_vector_get (y, j);
        yj += 1.0/cnode->rep * gsl_vector_get (x, k);
        gsl_vector_set (y, j, yj);
    }

    return 0;
}

/**
 * @brief Computes \f$ \frac{\partial E}{\partial x} \f$.
 * @ingroup gnn_convergence_doc
 *
 * @param    node A pointer to the \ref gnn_convergence node.
 * @param x  The input vector \f$x\f$.
 * @param w  The parameter vector \f$w\f$.
 * @param dy The vector \f$\frac{\partial E}{\partial y}\f$.
 * @param dx The output buffer vector \f$\frac{\partial E}{\partial x}\f$.
 * @return Returns 0 on success.
 */
static int
gnn_convergence_dx (gnn_node *node,
                    const gsl_vector *x,
                    const gsl_vector *w,
                    const gsl_vector *dy,
                    gsl_vector *dx)
{
    size_t n;
    size_t m;
    size_t k;
    gnn_convergence *cnode;

    /* get views */
    cnode = (gnn_convergence *) node;

    /* get input and output size */
    n = gnn_node_input_get_size (node);
    m = gnn_node_output_get_size (node);

    /* evaluate */
    for (k=0; k<n; ++k)
    {
        size_t j;
        double dxk;
        
        j   = k % m;
        dxk = cnode->rep * gsl_vector_get (dy, j);
        gsl_vector_set (dx, k, dxk);
    }

    return 0;
}

/**
 * @brief Computes \f$ \frac{\partial E}{\partial w} \f$.
 * @ingroup gnn_convergence_doc
 *
 * @param    node A pointer to the \ref gnn_convergence node.
 * @param x  The input vector \f$x\f$.
 * @param w  The parameter vector \f$w\f$.
 * @param dy The vector \f$\frac{\partial E}{\partial y}\f$.
 * @param dx The output buffer vector \f$\frac{\partial E}{\partial w}\f$.
 * @return Returns 0 on success.
 */
static int
gnn_convergence_dw (gnn_node *node,
                    const gsl_vector *x,
                    const gsl_vector *w,
                    const gsl_vector *dy,
                    gsl_vector *dw)
{
    return 0;
}



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

/**
 * @brief Creates an input convergence node.
 * @ingroup gnn_convergence_doc
 *
 * This function creates a node of the \ref gnn_convergence type.
 *
 * @param input_size  The input size \f$n\f$.
 * @param output_size The output size \f$m\f$.
 * @return A pointer to a new \ref gnn_convergence node.
 */
gnn_node *
gnn_convergence_new (size_t input_size, size_t output_size)
{
    int status;
    size_t k;
    gnn_node *node;
    gnn_convergence *cnode;

    /* check sizes */
    if (output_size < 1)
    {
        GSL_ERROR_VAL ("output size should be strictly positive",
                       GSL_EINVAL, NULL);
    }
    if (input_size < output_size)
    {
        GSL_ERROR_VAL ("input size should be greater than the output size",
                       GSL_EINVAL, NULL);
    }

    /* allocate the node */
    cnode = (gnn_convergence *) malloc (sizeof (gnn_convergence));
    if (cnode == NULL)
    {
        GSL_ERROR_VAL ("could not allocate memory for gnn_convergence node",
                       GSL_ENOMEM, NULL);
    }

    /* get view as a gnn_node */
    node = (gnn_node *) cnode;

    /* Initialize the node */
    status = gnn_node_init (node,
                            "gnn_convergence",
                            gnn_convergence_f,
                            gnn_convergence_dx,
                            gnn_convergence_dw,
                            NULL);
    if (status)
    {
        GSL_ERROR_VAL ("could not initialize gnn_convergence node",
                       GSL_EFAILED, NULL);
    }

    status = gnn_node_set_sizes (node, input_size, output_size, 0);
    if (status)
    {
        GSL_ERROR_VAL ("could not set sizes for gnn_convergence node",
                       GSL_EFAILED, NULL);
    }

    /* compute amount of replications */
    cnode->rep = input_size / output_size;
    cnode->rep += (input_size % output_size == 0)? 0 : 1;

    return node;
}

---