---

gnn_quadric.c

Go to the documentation of this file.

/***************************************************************************
 *  @file gnn_quadric.c
 *  @brief Quadric Discriminant Transfer Function.
 *
 *  @date   : 06-08-03 18:17, 22-08-03 23:04
 *  @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_quadric_doc gnn_quadric : Quadric Discriminant Activation Function.
 * @ingroup gnn_atomic_doc
 *
 * This node type takes the \f$n\f$ input variables \f$x_1, x_2, \ldots, x_n\f$
 * and produces \f$m = \frac{ n(n+1) }{2}\f$ outputs, corresponding to the
 * cross-multiplication of the inputs:
 * \f[ y_k = x_i x_j \f]
 * where \f$ k = n(i-1)+j-i? \f$, 
 * \f$ i? = 1 + 2 + 3 + \cdots + i= \sum_{j=1}^i j = \frac{ n(n+1) }{2}\f$.
 *
 * Example:
 * \f[ F([x_1, x_2, x_3]^t) =
 *      [x_1^2, x_1 x_2, x_1 x_3, x_2^2, x_2 x_3, x_3^2 ]^t \f]
 *
 * The resulting terms, combinend with a linear transform, can model quadric
 * decision boundaries (parabola, hyperbola, ellipsoids and spheres), which
 * are richer in structure than classic linear discriminants.
 *
 * Note: \f[ k(i,j) = \frac{2ni - 2n - i^2 + i}{2} + j
 *                  = n(i-1) + \frac{i(1-i)}{2} + j \f]
 */


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

#include "gnn_quadric.h"
#include <math.h>



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

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

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



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

/**
 * @brief Computes the output.
 * @ingroup gnn_quadric_doc
 *
 * This functions evaluates the Quadric Discriminant Transfer function.
 *
 * @param  node A pointer to a \ref gnn_quadric 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_quadric_f (gnn_node *node,
               const gsl_vector *x,
               const gsl_vector *w,
               gsl_vector *y)
{
    int i;
    int j;
    int k;
    int size;

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

    /* evaluate */
    k = 0;
    for (i=0; i<size; ++i)
    {
        for (j=i; j<size; ++j)
        {
            double xi;
            double xj;
            double yk;

            xi = gsl_vector_get (x, i);
            xj = gsl_vector_get (x, j);
            yk = xi * xj;
            gsl_vector_set (y, k, yk);
            
            k++;
        }
    }

    return 0;
}

/**
 * @brief Computes \f$ \frac{\partial E}{\partial x} \f$.
 * @ingroup gnn_quadric_doc
 *
 * This functions computes the gradient of the Quadric Discriminant activation
 * function, given dy (\f$ \frac{\partial E}{\partial y} \f$). The function
 * is,
 * \f[ \frac{\partial E}{\partial x_i} =
 *     \sum_{j=1, j \neq i}^n x_j \frac{\partial E}{\partial y_{k(i,j)}}
 *     + 2 x_i \frac{\partial E}{\partial y_{k(i,i)}}
 * \f]
 *
 * @param  node A pointer to a \ref gnn_quadric 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_quadric_dx (gnn_node *node,
                const gsl_vector *x,
                const gsl_vector *w,
                const gsl_vector *dy,
                gsl_vector *dx)
{
    int i;
    int j;
    int N;
    int k;

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

    /* compute the dx vector - Caution: The simmetry involved allows
       us to write a faster routine. */
    k = 0;
    for (i=0; i<N; ++i)
    {
        for (j=i; j<N; ++j)
        {
            double xi;
            double xj;
            double dyk;
            double dxi;
            double dxj;

            xi  = gsl_vector_get (x, i);
            xj  = gsl_vector_get (x, j);
            dyk = gsl_vector_get (dy, k);
            
            dxi = xj * dyk;
            gsl_vector_set (dx, i, dxi);

            dxj = gsl_vector_get (dx, j);
            dxj += xi * dyk;
            gsl_vector_set (dx, j, dxj);
            
            k++;
        }
    }

    return 0;
}


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

/**
 * @brief Creates a Quadric Discriminant Transfer function node.
 * @ingroup gnn_quadric_doc
 *
 * This function creates a node of the gnn_quadric type. This node
 * produces the second-order terms of its inputs. For a complete review,
 * see \ref gnn_quadric_doc.
 *
 * @param input_size The input size \f$n\f$.
 * @return A pointer to a new \ref gnn_quadric node.
 */
gnn_node *
gnn_quadric_new (int input_size)
{
    int status;
    int output_size;
    gnn_node *node;

    /* check if sizes are positive */
    if (input_size < 1)
    {
        GSL_ERROR_VAL ("size for gnn_quadric should be greater than 1",
                       GSL_EINVAL, NULL);
    }

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

    /* initialize node */
    status = gnn_node_init (node,
                            "gnn_quadric",
                            gnn_quadric_f,
                            gnn_quadric_dx,
                            NULL,
                            NULL);
    if (status)
    {
        free (node);
        GSL_ERROR_VAL ("could not initialize gnn_quadric node",
                       GSL_EFAILED, NULL);
    }

    /* set sizes */
    output_size = (input_size * (input_size + 1)) / 2;
    gnn_node_set_sizes (node, input_size, output_size, 0);

    return node;
}

---