---

gnn_criterion.c

Go to the documentation of this file.

/***************************************************************************
 *  @file gnn_criterion.h
 *  @brief Basic Structure for Criterions.
 *
 *  @date   : 24-08-03 19:28
 *  @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 The common (underlying) data structure for criterions.
 * @defgroup gnn_criterion_doc gnn_criterion : Basic Criterion Function.
 * @ingroup libgnn_criterion
 * @todo 1) Document the datatypes... gnn_criterion and its function types...
 *       2) Implement "evaluate" and "eval"
 *
 * A criterion is a special structure used for measuring the quality of a given
 * model. It implements a function
 * \f$E: \mathbb{R}^m \times \mathbb{R}^m \rightarrow \mathbb{R}\f$ that takes
 * two input vectors \f$y \in \mathbb{R}^m\f$ and \f$t \in \mathbb{R}^m\f$ as
 * arguments, and computes a cost value \f$ E(y,t) \f$ that should be minimized
 * during training.
 *
 * Normally, \f$E(y,t)\f$ measures the error or distance between the vectors
 * \f$y\f$ and \f$t\f$. This is important, because when modelling, the aim
 * is to minimize the error of the Model, that is, the estimation
 * \f[ F(x, w) = y \f]
 * should be similar to the desired output \f$t\f$.
 *
 * In order to use the criterion during training, which is almost always an
 * optimization process which uses the gradient
 * \f$\frac{\partial E}{\partial w}\f$, the function's gradient with respect
 * to \f$y\f$, that is, \f$\frac{\partial E}{\partial y}\f$, should be
 * available.
 *
 * \ref libgnn provides a common structure for criterions with the
 * \ref gnn_criterion and its associated functions. The \ref gnn_criterion
 * data type is a generic structure, which needs to be extended in order to be
 * usable. Basically, the structure should be equipped with an evaluation
 * function and a gradient evaluation function.
 *
 * To create a new criterion, you have two options:
 * - use one of the ready-to-use criterions
 * - implement your own criterion
 *
 * To use one of the available criterions, just create it using its constructor
 * function. In example, to create a \ref gnn_mean_square criterion, invoke
 * \code
   gnn_criterion *crit;
   
   crit = gnn_mean_square_new (10);
 * \endcode
 * which creates a new criterion of size 10.
 *
 * All criterion conform to a common interface, which is:
 * - \ref gnn_criterion_evaluate_e : Evaluates the criterion given a vector
 *   \f$y\f$ and a target \f$t\f$.
 * - \ref gnn_criterion_evaluate_dy : Evaluates the gradient
 *   \f$ \frac{\partial E}{\partial y} \f$ for the last evaluated \f$ y \f$
 *   and \f$ t \f$ vectors.
 * - \ref gnn_criterion_destroy : Destroys a criterion (by freeing its memory).
 * Each of these functions behave different for the specific type of criterion.
 *
 *
 * To implement a new criterion, you have to provide 3 specific functions
 * to be called by those mentioned above and install them into the
 * \ref gnn_criterion structure using the \ref gnn_criterion_init function.
 *
 * The 3 specific functions are of the following types:
 * - \ref gnn_criterion_e : A function that computes the value of the criterion
 *   or cost using \f$y\f$ and \f$t\f$.
 * - \ref gnn_criterion_dy : A function that computes the gradient
 *   \f$\frac{\partial E}{\partial y}\f$
 * - \ref gnn_criterion_destructor : A destructor for the specific extension's
 *   data.
 *
 * If your own criterion need additional resources, such as additional
 * parameters, then you have to extend the \ref gnn_criterion with the
 * additional fields that are needed. Remember to deallocate the specific
 * memory in your destructor, like in a \ref gnn_node.
 *
 * Another different form of a \ref gnn_criterion is a regularizator.
 * It performs a regularization of the error function, in the form:
 *
 * \f[ \widetilde{E} = E + \nu \Omega \f]
 *
 * where \f$E\f$ is an error criterion, called the "subcriterion" in
 * \ref libgnn, and \f$\Omega\f$ is a regularization term. The scalar
 * \f$\nu\f$ is called the regularization coefficient, which determines
 * the extent in which the regularization term affects the overall resulting
 * error \f$\widetilde{E}\f$. Regularization do limit the \ref gnn_node's
 * function complexity in order to perform better in generalization.
 * A regularization term usually penalizes the curvature of the output
 * mapping. Some of them (e.g. \em Weight \em Decay) depend directly on
 * the values of the function's parameters. They do coexist with a
 * \ref gnn_criterion, and need an error function upon construction.
 */



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

#include <string.h>
#include "gnn_criterion.h"



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

/**
 * @brief Initializes a \ref gnn_criterion.
 * @ingroup gnn_criterion_doc
 *
 * This function initializes a \ref gnn_criterion by setting its size and
 * installing the specific functions for \f$ E \f$,
 * \f$ \frac{\partial E}{\partial y} \f$ and the destructor.
 *
 * It is mandatory to provide:
 * - A size that is stricly positive.
 * - The evaluation function.
 * - The gradient evaluation function.
 *
 * If the destructor is ommitted (by giving NULL as argument), then it will
 * be assumed that no special deallocation is necessary for the extension.
 *
 * In example, suppose you want to implement a criterion called "my_criterion"
 * and that you have already coded the evaluation function and the gradient
 * function, which you called "my_criterion_e" and "my_criterion_dy"
 * respectivelly. Your criterion doesn't need any additional data to compute
 * them, so you didn't extend the basic \ref gnn_criterion. Then, the
 * code would be a template for the constructor:
 * \code
   gnn_criterion *
   my_criterion_new (size_t size)
   {
       int status;
       gnn_criterion *crit;
       
       // allocate memory for the criterion
       crit = (gnn_criterion *) malloc (sizeof (gnn_criterion));
       
       // initialize
       status = gnn_criterion_init (crit, "my criterion", size,
                       my_criterion_e, my_criterion_dy, my_criterion_destroy);
       if (status)
           print_an_error_message_and_return_null ();

       // return
       return crit;
   }
 * \endcode
 *
 * @param  crit    A pointer to a \ref gnn_criterion.
 * @param  type    A string containing the name of the criterion.
 * @param  size    The size of the input vectors \f$ y \f$ and \f$ t \f$.
 * @param  e       A pointer to the evaluation function.
 * @param  dy      A pointer to the gradient evaluation function.
 * @param  destroy A pointer to the destructor function.
 * @return Returns 0 if the initialization could be performed with success.
 */
int
gnn_criterion_init (gnn_criterion *crit,
                    const char    *type,
                    size_t         size,
                    gnn_criterion_e          e,
                    gnn_criterion_dy         dy,
                    gnn_criterion_destructor destroy)
{
    int status;
    
    assert (crit != NULL);
    assert (type != NULL);
    
    /* check size */
    if (size < 1)
        GSL_ERROR ("gnn_criterion size should be stricly positive", GSL_EINVAL);
    
    /* set the criterion's fields */
    crit->type    = strdup (type);
    crit->m       = size;
    crit->e       = NULL;
    crit->dy      = NULL;
    crit->destroy = NULL;
    
    /* install functions */
    if (e == NULL)
    {
        GSL_ERROR ("gnn_criterion should have an evaluation function",
                   GSL_EINVAL);
    }
    else
        crit->e = e;
        
    if (dy == NULL)
    {
        GSL_ERROR ("gnn_criterion should have a gradient function",
                   GSL_EINVAL);
    }
    else
        crit->dy = dy;

    if (destroy != NULL)
        crit->destroy = destroy;
    
    return 0;
}

/**
 * @brief Returns a criterion's size.
 * @ingroup gnn_criterion_doc
 *
 * This functions returns the size \f$m\f$of the vectors \f$y\f$ and \f$t\f$.
 *
 * @param  crit A pointer to a \ref gnn_criterion.
 * @return Returns the size.
 */
size_t
gnn_criterion_get_size (gnn_criterion *crit)
{
    assert (crit != NULL);
    
    return crit->m;
}

/**
 * @brief Returns the name of the criterion.
 * @ingroup gnn_criterion_doc
 *
 * This functions returns a string which identifies uniquely the current
 * criterion's type.
 *
 * @param  crit A pointer to a \ref gnn_criterion.
 * @return Returns a non-modifiable string.
 */
const char *
gnn_criterion_get_type (gnn_criterion *crit)
{
    assert (crit != NULL);
    
    return crit->type;
}

/**
 * @brief Evaluates the criterion.
 * @ingroup gnn_criterion_doc
 *
 * This function evaluates the criterion for the given vectors "y" and "t",
 * which are (usually) the Models output \f$ y \f$ and the desired target
 * vector \f$ t \f$.
 *
 * It will call the specific evaluation function for the criterion, which
 * was previosly installed.
 *
 * @param  crit A pointer to a \ref gnn_criterion.
 * @param  y    A pointer to a vector (the estimation).
 * @param  t    A pointer to a vector (the target).
 * @return The value of the criterion.
 */
double
gnn_criterion_evaluate_e (gnn_criterion *crit,
                          const gsl_vector *y,
                          const gsl_vector *t)
{
    assert (crit != NULL);

    /* store vectors */
    crit->y = y;
    crit->t = t;

    /* evaluate */
    return crit->e (crit, y, t);
}

/**
 * @brief Evaluates the criterion's gradient.
 * @ingroup gnn_criterion_doc
 *
 * This function evaluates the criterion's gradient with respect to the
 * last evaluated estimation \f$y\f$ and target \f$t\f$. The gradient always
 * is of the same size. Internally, it clears the buffer "dy" (where the
 * resulting gradient should be placed in) and then calls
 * \ref gnn_criterion_evaluate.
 *
 * @param  crit A pointer to a \ref gnn_criterion.
 * @param  dy   A pointer to a buffer vector of the correct size for
 *              storing the gradient.
 * @return Returns 0 if succeeded.
 */
int
gnn_criterion_evaluate_dy (gnn_criterion *crit,
                           gsl_vector *dy)
{
    assert (crit != NULL);

    /* clear buffer */
    gsl_vector_set_zero (dy);

    /* evaluate */
    return gnn_criterion_eval_dy (crit, dy);
}

/**
 * @brief Evaluates the criterion's gradient.
 * @ingroup gnn_criterion_doc
 *
 * This function evaluates the criterion's gradient with respect to the
 * last evaluated estimation \f$y\f$ and target \f$t\f$ and ADDS the result
 * to the vector pointed by "dy". It is important to note the following rules:
 *
 * - This function is called by \ref gnn_criterion_evaluate_dy.
 * - Composed criterions, which depend on inner subcriterions often need
 *   to compute their gradient as the result of summing up their subgradients.
 *
 * This is why the evaluation of the gradient has been split up into the
 * base function \ref gnn_criterion_evaluate_dy (which clears the buffer
 * "dy" first) and this function.
 *
 * This function calls the criterion's specific gradient function.
 *
 * @param  crit A pointer to a \ref gnn_criterion.
 * @param  dy   A pointer to a buffer vector of the correct size where the
 *              gradient \f$\frac{\partial E}{\partial y}\f$ is added up.
 * @return Returns 0 if succeeded.
 */
int
gnn_criterion_eval_dy (gnn_criterion *crit,
                           gsl_vector *dy)
{
    /* evaluate */
    return crit->dy (crit, crit->y, crit->t, dy);
}

/**
 * @brief Destroys the criterion.
 * @ingroup gnn_criterion_doc
 *
 * This function destroys a given criterion structure by freeing its memory.
 *
 * It will call the specific destroy function (if any) for the criterion, which
 * was previosly installed. Then it frees the fields of \ref gnn_criterion and
 * the structure itself.
 *
 * @param  crit A pointer to a \ref gnn_criterion.
 */
void
gnn_criterion_destroy (gnn_criterion *crit)
{
    assert (crit != NULL);
    
    if (crit->destroy != NULL)
        crit->destroy (crit);
    
    free ((char *) crit->type);
    free (crit);
}

---