---

gnn_prototype.c

Go to the documentation of this file.

/***************************************************************************
 *  @file gnn_prototype.c
 *  @brief Prototype Implementation File.
 *
 *  @date   : 17-09-03 20:52
 *  @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_prototype_doc gnn_prototype : Prototypes.
 * @ingroup gnn_atomic_doc
 *
 * The \ref gnn_prototype datatype implements a set of prototypes in
 * \f$\mathbb{R}^n\f$, which are compared against the input vectors.
 * The function computed by this node is:
 *
 * \f[ y_j = \sqrt{ \sum_{i=1}^n (w^j_i - x_i)^2 } \f]
 *
 * where \f$w^j\f$ is the \f$j\f$-th prototype. In other words, the outputs
 * \f$y_j\f$ measure the euclidian distance to each one of the prototypes.
 *
 * The function's gradients are:
 *
 * \f[ \frac{\partial E}{\partial x_i}
 *     = - \frac{1}{2} \left (
 *           \sum_{i=1}^n (w_i^j - x_i)^2
 *                     \right )^{-\frac{1}{2}} 2 (w_i^j - x_i)
 *         \frac{\partial E}{\partial y}
 *     = - \frac{w_i^k - x_i}{y_j} \frac{\partial E}{\partial y}
 * \f]
 * and
 * \f[ \frac{\partial E}{\partial w^j_i}
 *     = \frac{1}{2} \left (
 *           \sum_{i=1}^n (w_i^j - x_i)^2
 *                     \right )^{-\frac{1}{2}} 2 (w_i^j - x_i)
 *       \frac{\partial E}{\partial y}
 *     = \frac{w_i^k - x_i}{y_j} \frac{\partial E}{\partial y}
 * \f]
 * The prototypes are very effective in cojunction with a kernel function,
 * like \ref gnn_gaussian, thus forming a Kernel Model.
 */



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

#include "gnn_prototype.h"
#include "gnn_utilities.h"
#include <gsl/gsl_blas.h>
#include <math.h>



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

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

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

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

static void
gnn_prototype_destroy (gnn_node *node);



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

/**
 * @brief Computes the output.
 * @ingroup gnn_prototype_doc
 *
 * This functions evaluates the distance to the prototypes.
 *
 * @param node  A pointer to a \ref gnn_prototype 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_prototype_f (gnn_node *node,
                 const gsl_vector *x,
                 const gsl_vector *w,
                 gsl_vector *y)
{
    size_t j;
    size_t m;
    gnn_prototype *pnode;
    gsl_vector_view wj;

    /* get the sizes */
    m = gnn_node_output_get_size (node);

    /* get gnn_prototype view */
    pnode = (gnn_prototype *) node;

    /* evaluate */
    for (j=0; j<m; ++j)
    {
        double yj;

        /* compute euclidean distance to prototype */
/*
        wj = gsl_matrix_row (pnode->D, j);
        gsl_vector_memcpy (pnode->row, &(wj.vector));
        gsl_vector_sub (pnode->row, x);
        yj = gsl_blas_dnrm2 (pnode->row);
*/

        wj = gsl_matrix_row (pnode->D, j);
        yj = gnn_vector_euclidian_dist (&(wj.vector), x);

        /* set distance */
        gsl_vector_set (pnode->y, j, yj);
    }

    /* sum result from buffer */
    gsl_vector_memcpy (y, pnode->y);

    return 0;
}

/**
 * @brief Computes \f$ \frac{\partial E}{\partial x} \f$.
 * @ingroup gnn_prototype_doc
 *
 * This functions computes the gradient of the distance to the prototypes
 * with respect to the inputs. That is,
 * \f[ \frac{\partial E}{\partial x_i}
 *     = - \sum_{j=1}^m \frac{w^j_i - x_i}{y_j} \frac{\partial E}{\partial y_j}
 * \f]
 *
 * @param node  A pointer to a \ref gnn_prototype 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_prototype_dx (gnn_node *node,
                  const gsl_vector *x,
                  const gsl_vector *w,
                  const gsl_vector *dy,
                  gsl_vector *dx)
{
    size_t i;
    size_t n;
    gnn_prototype *pnode;
    gsl_vector_view wi;

    /* get the size */
    n = gnn_node_input_get_size (node);

    /* get gnn_prototype view */
    pnode = (gnn_prototype *) node;

    /* evaluate */
    for (i=0; i<n; ++i)
    {
        double xi;
        double dxi;

        /* get i-th component */
        xi  = gsl_vector_get (x, i);
        //dxi = gsl_vector_get (dx, i);

        /* compute dyj/dxi */
        gsl_vector_set_all (pnode->col, xi);
        wi = gsl_matrix_column (pnode->D, i);
        gsl_vector_sub (pnode->col, &(wi.vector));
        gsl_vector_div (pnode->col, pnode->y);

        /* compute dE/dxi */
        gsl_vector_mul (pnode->col, dy);
        //dxi += gnn_vector_sum_elements (pnode->col);
        dxi = gnn_vector_sum_elements (pnode->col);

        /* set dxi */
        gsl_vector_set (dx, i, dxi);
    }

    return 0;
}

/**
 * @brief Computes \f$ \frac{\partial E}{\partial w} \f$.
 * @ingroup gnn_prototype_doc
 *
 * This functions computes the gradient of the distance to the prototypes
 * with respect to the prototypes' position. That is,
 * \f[ \frac{\partial E}{\partial w^j_i}
 *     = \frac{w^j_i - x_i}{y_j} \frac{\partial E}{\partial y_j}
 * \f]
 *
 * @param node  A pointer to a \ref gnn_prototype 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 dw The output buffer vector \f$\frac{\partial E}{\partial w}\f$.
 * @return Returns 0 on success.
 */
static int
gnn_prototype_dw (gnn_node *node,
                  const gsl_vector *x,
                  const gsl_vector *w,
                  const gsl_vector *dy,
                  gsl_vector *dw)
{
    size_t j;
    size_t m;
    gnn_prototype *pnode;
    gsl_vector_view wj;
    gsl_vector_view dwj;

    /* get the sizes */
    m = gnn_node_output_get_size (node);

    /* get gnn_prototype view */
    pnode = (gnn_prototype *) node;

    /* evaluate (compute row-wise) */
    for (j=0; j<m; ++j)
    {
        double yj;
        double dyj;

        /* get output y and dy */
        yj  = gsl_vector_get (pnode->y, j);
        dyj = gsl_vector_get (dy, j);

        /* compute dE/dwj */
        wj = gsl_matrix_row (pnode->D, j);
        gsl_vector_memcpy (pnode->row, &(wj.vector));
        gsl_vector_sub (pnode->row, x);
        gsl_vector_scale (pnode->row, dyj / yj);

        /* set dE/dwj */
        dwj = gsl_matrix_row (pnode->dD, j);
        gsl_vector_add (&(dwj.vector), pnode->row);
    }

    return 0;
}

/**
 * @brief The \ref gnn_prototype destroy function.
 * @ingroup gnn_prototype_doc
 *
 * This functions is the \ref gnn_prototype destroy function.
 *
 * @param  node A node to an \ref gnn_prototype.
 */
static void
gnn_prototype_destroy (gnn_node *node)
{
    gnn_prototype *pnode;

    assert (node != NULL);
    
    pnode = (gnn_prototype *) node;
    
    if (pnode->y != NULL)
        gsl_vector_free (pnode->y);
    if (pnode->row != NULL)
        gsl_vector_free (pnode->row);
    if (pnode->col != NULL)
        gsl_vector_free (pnode->col);

    return;
}



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

/**
 * @brief Creates a Prototype node.
 * @ingroup gnn_prototype_doc
 *
 * This function creates a node of the \ref gnn_prototype type. Each one
 * of its vectors is drawn from a uniform distribution between
 * [min; max).
 *
 * @param input_size  The input size \f$n\f$.
 * @param output_size The output size \f$m\f$, and the number of prototypes.
 * @param min         The minimum value of a component.
 * @param max         The maximum value of a component.
 * @return A pointer to a new \ref gnn_prototype node.
 */
gnn_node *
gnn_prototype_new (size_t input_size, size_t output_size,
                                              double min, double max)
{
    int status;
    size_t i, j;
    gsl_rng  *rng;
    gnn_node *node;
    gnn_prototype *pnode;
    gsl_vector *w;
    gsl_vector *dw;
    gsl_vector_int *f;

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

    /* check interval */
    if (min >= max)
    {
        GSL_ERROR_VAL ("min should be smaller than max",
                       GSL_EINVAL, NULL);
    }

    /* allocate the node */
    pnode = (gnn_prototype *) malloc (sizeof (gnn_prototype));
    if (pnode == NULL)
    {
        GSL_ERROR_VAL ("couldn't allocate memory for gnn_prototype",
                       GSL_ENOMEM, NULL);
    }
    
    /* get view as gnn_node */
    node = (gnn_node *) pnode;

    /* Initialize the node */
    status = gnn_node_init (node,
                            "gnn_prototype",
                            gnn_prototype_f,
                            gnn_prototype_dx,
                            gnn_prototype_dw,
                            gnn_prototype_destroy);
    if (status)
    {
        free (node);
        GSL_ERROR_VAL ("could not initialize gnn_prototype node",
                       GSL_EINVAL, NULL);
    }

    /* set sizes */
    status = gnn_node_set_sizes (node,  input_size,
                                        output_size, input_size * output_size);
    if (status)
    {
        gnn_node_destroy (node);
        GSL_ERROR_VAL ("could not set sizes for gnn_prototype node",
                       GSL_EFAILED, NULL);
    }

    /* Allocate memory for buffers */
    pnode->y   = gsl_vector_alloc (output_size);
    pnode->row = gsl_vector_alloc (input_size);
    pnode->col = gsl_vector_alloc (output_size);
    if (pnode->y == NULL || pnode->row == NULL || pnode->col == NULL)
    {
        gnn_node_destroy (node);
        GSL_ERROR_VAL ("could not allocate buffers for gnn_prototype",
                       GSL_ENOMEM, NULL);
    }

    /* Get parameter views */
    w  = gnn_node_local_get_w (node);
    dw = gnn_node_local_get_dw (node);
    f  = gnn_node_local_get_f (node);
    
    pnode->D_view  = gsl_matrix_view_vector (w, output_size, input_size);
    pnode->dD_view = gsl_matrix_view_vector (dw, output_size, input_size);
    pnode->Df_view = gsl_matrix_int_view_vector (f, output_size, input_size);
    
    pnode->D  = &(pnode->D_view.matrix);
    pnode->dD = &(pnode->dD_view.matrix);
    pnode->Df = &(pnode->Df_view.matrix);

    /* initialize prototypes */
    rng = gnn_get_rng ();
    for (j=0; j<output_size; ++j)
        for (i=0; i<input_size; ++i)
        {
            double w;
            w = gsl_rng_uniform (rng);
            w = (max - min) * w + min;
            gsl_matrix_set (pnode->D, j, i, w);
        }

    /* update parameters */
    gnn_node_local_update (node);

    return node;
}

/**
 * @brief Creates a standard Prototype node.
 * @ingroup gnn_prototype_doc
 *
 * This function creates a node of the \ref gnn_prototype type. Each one
 * of its vectors is drawn from a uniform distribution between
 * [-1; 1).
 *
 * @param input_size  The input size \f$n\f$.
 * @param output_size The output size \f$m\f$, and the number of prototypes.
 * @return A pointer to a new \ref gnn_prototype node.
 */
gnn_node *
gnn_prototype_standard_new (size_t input_size, size_t output_size)
{
    return gnn_prototype_new (input_size, output_size, -1.0, 1.0);
}

/**
 * @brief Freeze a prototype.
 * @ingroup gnn_prototype_doc
 *
 * This function freezes the j-th prototype.
 *
 * @param node A pointer to a \ref gnn_prototype node.
 * @param j    The index of the prototype to be frozen.
 * @return Returns 0 if succeeded.
 */
int
gnn_prototype_vector_freeze (gnn_node *node, size_t j)
{
    gnn_prototype *pnode;
    gsl_vector_int_view v;

    assert (node != NULL);

    /* get view */
    pnode = (gnn_prototype *) node;

    /* check for boundaries */
    if (j < 0 || j >= pnode->Df->size1)
    {
        GSL_ERROR ("index out of bounds", GSL_EINVAL);
    }

    /* get freeze flags */
    gnn_node_local_get_f (node);

    /* get vector view */
    v = gsl_matrix_int_row (pnode->Df, j);

    /* freeze vector */
    gsl_vector_int_set_all (&(v.vector), 1);

    /* update parameters */
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Unfreeze a prototype.
 * @ingroup gnn_prototype_doc
 *
 * This function unfreezes the j-th prototype.
 *
 * @param node A pointer to a \ref gnn_prototype node.
 * @param j    The index of the prototype to be unfrozen.
 * @return Returns 0 if succeeded.
 */
int
gnn_prototype_vector_unfreeze (gnn_node *node, size_t j)
{
    gnn_prototype *pnode;
    gsl_vector_int_view v;

    assert (node != NULL);

    /* get view */
    pnode = (gnn_prototype *) node;

    /* check for boundaries */
    if (j < 0 || j >= pnode->Df->size1)
    {
        GSL_ERROR ("index out of bounds", GSL_EINVAL);
    }

    /* get freeze flags */
    gnn_node_local_get_f (node);

    /* get vector view */
    v = gsl_matrix_int_row (pnode->Df, j);

    /* freeze vector */
    gsl_vector_int_set_zero (&(v.vector));

    /* update parameters */
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Sets a prototype.
 * @ingroup gnn_prototype_doc
 *
 * This function sets a new value for the j-th prototype.
 *
 * @param node A pointer to a \ref gnn_prototype node.
 * @param j    The index of the prototype to be frozen.
 * @param v    A new with the new values for the prototype.
 * @return Returns 0 if succeeded.
 */
int
gnn_prototype_vector_set (gnn_node *node, size_t j, const gsl_vector *v)
{
    gsl_vector_view u;
    gnn_prototype *pnode;

    assert (node != NULL);

    /* get view */
    pnode = (gnn_prototype *) node;

    /* check for boundaries */
    if (j < 0 || j >= pnode->D->size1)
    {
        GSL_ERROR ("index out of bounds", GSL_EINVAL);
    }

    /* check size */
    if (gnn_node_input_get_size (node) != v->size)
    {
        GSL_ERROR ("vector insn't of the correct size", GSL_EINVAL);
    }

    /* get parameters */
    gnn_node_local_get_w (node);

    /* get vector view */
    u = gsl_matrix_row (pnode->D, j);

    /* copy vector */
    gsl_vector_memcpy (&(u.vector), v);

    /* update parameters */
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Gets a prototype.
 * @ingroup gnn_prototype_doc
 *
 * This function gets the values of the j-th prototype and stores them
 * into the given vector.
 *
 * @param node A pointer to a \ref gnn_prototype node.
 * @param j    The index of the prototype to be frozen.
 * @param v    A vector of the correct size, where the prototype's values
 *             should be copied in.
 * @return Returns 0 if succeeded.
 */
int
gnn_prototype_vector_get (gnn_node *node, size_t j, gsl_vector *v)
{
    gsl_vector_view u;
    gnn_prototype *pnode;

    assert (node != NULL);

    /* get view */
    pnode = (gnn_prototype *) node;

    /* check for boundaries */
    if (j < 0 || j >= pnode->D->size1)
    {
        GSL_ERROR ("index out of bounds", GSL_EINVAL);
    }

    /* check size */
    if (gnn_node_input_get_size (node) != v->size)
    {
        GSL_ERROR ("vector insn't of the correct size", GSL_EINVAL);
    }

    /* get parameters */
    gnn_node_local_get_w (node);

    /* get vector view */
    u = gsl_matrix_row (pnode->D, j);

    /* copy vector */
    gsl_vector_memcpy (v, &(u.vector));

    /* update parameters */
    gnn_node_local_update (node);

    return 0;
}

---