---

gnn_evaluation.h

Go to the documentation of this file.

/***************************************************************************
 *  @file gnn_evaluation.h
 *  @brief Evaluation Header File.
 *
 *  @date   : 16-09-03 23:47
 *  @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.
 */

#ifndef _GNN_EVALUATION_H_
#define _GNN_EVALUATION_H_

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

#include <gsl/gsl_matrix.h>
#include "gnn_node.h"
#include "gnn_criterion.h"
#include "gnn_dataset.h"
#include "gnn_output.h"



/******************************************/
/* Macros                                 */
/******************************************/

/************************************/
/* a) Input Examples Evaluation     */
/************************************/

/**
 * @brief Returns a pointer to the associated \ref gnn_node.
 * @ingroup gnn_evaluation_doc
 *
 */
#define GNN_EVAL_GET_NODE(eval) ((eval)->node)

/**
 * @brief Returns a pointer to the associated \ref gnn_input.
 * @ingroup gnn_evaluation_doc
 *
 */
#define GNN_EVAL_GET_INPUT(eval) ((eval)->in)

/**
 * @brief Returns a pointer to the associated \ref gnn_output.
 * @ingroup gnn_evaluation_doc
 *
 */
#define GNN_EVAL_GET_OUTPUT(eval) ((eval)->out)

/**
 * @brief Returns the size of the input.
 * @ingroup gnn_evaluation_doc
 *
 */
#define GNN_EVAL_INPUT_SIZE(eval) ((eval)->n)

/**
 * @brief Returns the size of the output.
 * @ingroup gnn_evaluation_doc
 *
 */
#define GNN_EVAL_OUTPUT_SIZE(eval) ((eval)->m)

/**
 * @brief Returns the size of the parameter vector.
 * @ingroup gnn_evaluation_doc
 *
 */
#define GNN_EVAL_PARAMETER_SIZE(eval) ((eval)->l)

/**
 * @brief Returns the amount of examples to be evaluated by the \ref gnn_eval.
 * @ingroup gnn_evaluation_doc
 *
 * This macro returns the number of examples to be evaluated by the
 * \ref gnn_eval evaluation buffer. Basically, it is the number of
 * examples contained in the associated \ref gnn_input object.
 */
#define GNN_EVAL_AMOUNT(eval) ((eval)->P)



/************************************/
/* b) Error and Gradient Evaluation */
/************************************/

/**
 * @brief Returns a pointer to the associated \ref gnn_node.
 * @ingroup gnn_evaluation_doc
 *
 */
#define GNN_GRAD_GET_NODE(grad) ((grad)->node)

/**
 * @brief Returns a pointer to the associated \ref gnn_input.
 * @ingroup gnn_evaluation_doc
 *
 */
#define GNN_GRAD_GET_INPUT(grad) ((grad)->in)

/**
 * @brief Returns a pointer to the associated \ref gnn_output.
 * @ingroup gnn_evaluation_doc
 *
 */
#define GNN_GRAD_GET_OUTPUT(grad) ((grad)->out)

/**
 * @brief Returns the size of the input.
 * @ingroup gnn_evaluation_doc
 *
 */
#define GNN_GRAD_INPUT_SIZE(grad) ((grad)->n)

/**
 * @brief Returns the size of the output.
 * @ingroup gnn_evaluation_doc
 *
 */
#define GNN_GRAD_OUTPUT_SIZE(grad) ((grad)->m)

/**
 * @brief Returns the size of the parameter vector.
 * @ingroup gnn_evaluation_doc
 *
 */
#define GNN_GRAD_PARAMETER_SIZE(grad) ((grad)->l)

/**
 * @brief Returns the amount of examples considered by the \ref gnn_grad.
 * @ingroup gnn_evaluation_doc
 *
 * This macro returns the number of examples considered in the computation
 * of the weighted values. Basically, it is the number of
 * examples contained in the associated \ref gnn_dataset object.
 */
#define GNN_GRAD_AMOUNT(grad) ((grad)->P)

/**
 * @brief Returns the last pattern weight sum.
 * @ingroup gnn_evaluation_doc
 *
 * This macro returns the sum
 * \f[ \sum_{k=s}^{s+n} p_k \f]
 * of the last processed minibatch in the given \ref gnn_grad buffer.
 */
#define GNN_GRAD_SUMP(grad) ((grad)->mp)

/**
 * @brief Returns the last pattern weight sum.
 * @ingroup gnn_evaluation_doc
 *
 * This macro returns the sum
 * \f[ \sum_{k=s}^{s+n} p_k \f]
 * of the last processed minibatch in the given \ref gnn_grad buffer.
 */
#define GNN_GRAD_SUMP(grad) ((grad)->mp)

/**
 * @brief Returns the sum of the last batch's error.
 * @ingroup gnn_evaluation_doc
 *
 * This macro returns the last sum of errors, given by
 * \f[ <E> = \sum_{k=s}^{s+n} p_k E_k \f]
 * for the last processed minibatch in the given \ref gnn_grad buffer.
 */
#define GNN_GRAD_SUME(grad) ((grad)->mp * (grad)->me)

/**
 * @brief Returns the last batch's mean error sum.
 * @ingroup gnn_evaluation_doc
 *
 * This macro returns the last mean error, given by
 * \f[ <E> = \frac{1}{\sum_{k=s}^{s+n} p_k} \sum_{k=s}^{s+n} p_k E_k \f]
 * for the last processed minibatch in the given \ref gnn_grad buffer.
 */
#define GNN_GRAD_E(grad) ((grad)->me)

/**
 * @brief Returns the last batch's mean error sum.
 * @ingroup gnn_evaluation_doc
 *
 * This macro returns the last gradient with respect its inputs, given by
 * \f[ <\frac{\partial E}{\partial x}> =
 *         \frac{1}{\sum_{k=s}^{s+n} p_k}
 *             \sum_{k=s}^{s+n} p_k \frac{\partial E}{\partial x}^k \f]
 * for the last processed minibatch in the given \ref gnn_grad buffer.
 */
#define GNN_GRAD_DX(grad) ((grad)->mdx)

/**
 * @brief Returns the last batch's mean error sum.
 * @ingroup gnn_evaluation_doc
 *
 * This macro returns the last gradient with respect its parameters, given by
 * \f[ <\frac{\partial E}{\partial w}> =
 *         \frac{1}{\sum_{k=s}^{s+n} p_k}
 *             \sum_{k=s}^{s+n} p_k \frac{\partial E}{\partial w}^k \f]
 * for the last processed minibatch in the given \ref gnn_grad buffer.
 */
#define GNN_GRAD_DW(grad) ((grad)->mdw)



/****************************/
/* c) Error Line Evaluation */
/****************************/

/**
 * @brief Returns the origin of the line evaluations.
 * @ingroup gnn_evaluation_doc
 *
 * This macro returns a pointer to the origin \f$w_0\f$ where all directional
 * evaluations are evaluated at.
 */
#define GNN_LINE_W(line) ((line)->w)

/**
 * @brief Returns the direction of the line evaluations.
 * @ingroup gnn_evaluation_doc
 *
 * This macro returns a pointer to the directional vector \f$d\f$ where all
 * directional evaluations are evaluated at.
 */
#define GNN_LINE_DIR(line) ((line)->d)

/**
 * @brief Returns the last computed error along the line evaluation.
 * @ingroup gnn_evaluation_doc
 *
 * This macro returns the value of the last computed average error along the
 * last line evaluation.
 */
#define GNN_LINE_E(line) ((line)->error)

/**
 * @brief Returns the last computed derivative along the line evaluation.
 * @ingroup gnn_evaluation_doc
 *
 * This macro returns the value of the computed derivate along the
 * last line evaluation.
 */
#define GNN_LINE_DE(line) ((line)->derivative)



/******************************************/
/* Typedefs and Enums                     */
/******************************************/

/*************************/
/* a) Pattern Evaluation */
/*************************/

/**
 * @brief Evaluation buffer structure.
 * @ingroup gnn_evaluation_doc
 *
 * This structure contains the necessary elements for performing a full
 * dataset evaluation.
 */
typedef struct _gnn_eval gnn_eval;

struct _gnn_eval
{
    gnn_node   *node;    /**< Pointer to the associated \ref gnn_node      */
    gnn_input  *input;   /**< Pointer to the associated \ref gnn_input     */
    gnn_output *output;  /**< Pointer to the associated \ref gnn_output    */

    size_t      n;       /**< The input size                   */
    size_t      m;       /**< The output size                  */
    size_t      l;       /**< The number of parameters         */
    size_t      P;       /**< The number of available patterns */

    gsl_vector *y;       /**< Buffer for \f$y^k\f$ */
};



/************************************/
/* b) Error and Gradient Evaluation */
/************************************/

/**
 * @brief Error and Gradients Evaluation buffer structure.
 * @ingroup gnn_evaluation_doc
 *
 * This structure contains the necessary values and buffers for performing
 * the computation of averaged gradients and errors over datasets.
 */
typedef struct _gnn_grad gnn_grad;

struct _gnn_grad
{
    gnn_node      *node; /**< Pointer to the associated \ref gnn_node      */
    gnn_criterion *crit; /**< Pointer to the associated \ref gnn_criterion */
    gnn_dataset   *data; /**< Pointer to the associated \ref gnn_dataset   */

    size_t      n;       /**< The input size                   */
    size_t      m;       /**< The output size                  */
    size_t      l;       /**< The number of parameters         */
    size_t      P;       /**< The number of available patterns */

    double      p;       /**< Buffer for \f$p\f$ */
    double      e;       /**< Buffer for \f$E\f$ */
    gsl_vector *y;       /**< Buffer for \f$y\f$ */
    gsl_vector *w;       /**< Buffer for \f$w\f$ */
    gsl_vector *dy;      /**< Buffer for \f$\frac{\partial E}{\partial y}\f$ */
    gsl_vector *dx;      /**< Buffer for \f$\frac{\partial E}{\partial x}\f$ */
    gsl_vector *dw;      /**< Buffer for \f$\frac{\partial E}{\partial w}\f$ */
    gsl_vector *h;       /**< Auxiliary buffer for Hessian computing */

    /** Public Members **/

    double      mp;   /**< Sum of pattern weights \f$\sum p\f$              */
    double      me;   /**< Buffer for \f$<E>\f$                             */
    gsl_vector *mdx;  /**< Buffer for \f$<\frac{\partial E}{\partial y}>\f$ */
    gsl_vector *mdw;  /**< Buffer for \f$<\frac{\partial E}{\partial y}>\f$ */
};

/**
 * @brief Gradient evaluation flags.
 * @ingroup gnn_evaluation_doc
 *
 * This special datatype is used by the gradient evaluation functions. It
 * tells them how far the batch should be processed, i.e. if it should
 * compute \f$<E>\f$, \f$<\frac{\partial E}{\partial x}>\f$ and
 * \f$<\frac{\partial E}{\partial w}>\f$, in this order of dependence.
 */
typedef enum _gnn_grad_eval gnn_grad_eval;

enum _gnn_grad_eval {gnnGradE, gnnGradDx, gnnGradDw};



/****************************/
/* c) Error Line Evaluation */
/****************************/

/**
 * @brief Directional Error and Gradients Evaluation buffer structure.
 * @ingroup gnn_evaluation_doc
 *
 * This structure contains the necessary values and buffers for performing
 * the computation of averaged gradients and errors over datasets, evaluated
 * along a given direction, treating the node's function as a one-dimensional
 * function.
 *
 * The structure contains the direction and a error and gradient evaluation
 * buffer (\ref gnn_grad).
 */
typedef struct _gnn_line gnn_line;

struct _gnn_line
{
    gnn_grad   *grad;       /**< The error and gradient evaluation buffer. */
    
    gsl_vector *w;          /**< The center of evaluations.                */
    gsl_vector *d;          /**< The direction vector.                     */
    gsl_vector *dbuf;       /**< A buffer for direction evaluation.        */
    double      error;      /**< Last computed error along the given line. */
    double      derivative; /**< The derivative along the given line.      */
};

/**
 * @brief Line evaluation flags.
 * @ingroup gnn_evaluation_doc
 *
 * This special datatype is used by the line evaluation functions. It
 * tells them if they should computed only the error along the given
 * line or if they also should compute the error derivative.
 */
typedef enum _gnn_line_eval gnn_line_eval;

enum _gnn_line_eval {gnnLineE, gnnLineDE};



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

/*************************/
/* a) Pattern Evaluation */
/*************************/

gnn_eval *
gnn_eval_new (gnn_node *node, gnn_input *in, gnn_output *out);

void
gnn_eval_destroy (gnn_eval *eval);

int
gnn_eval_pats (gnn_eval *eval, size_t s, size_t n);

int
gnn_eval_all (gnn_eval *eval);


/************************************/
/* b) Error and Gradient Evaluation */
/************************************/

gnn_grad *
gnn_grad_new (gnn_node *node, gnn_criterion *crit, gnn_dataset *data);

void
gnn_grad_destroy (gnn_grad *grad);

int
gnn_grad_pats (gnn_grad *grad, gnn_grad_eval flag, size_t s, size_t n);

int
gnn_grad_all (gnn_grad *grad, gnn_grad_eval flag);


/****************************/
/* c) Error Line Evaluation */
/****************************/

gnn_line *
gnn_line_new (gnn_grad *grad, gsl_vector *direction);

void
gnn_line_destroy (gnn_line *line);

int
gnn_line_set_direction (gnn_line *line, const gsl_vector *dir);

const gsl_vector *
gnn_line_get_direction (gnn_line *line);

int
gnn_line_set_origin (gnn_line *line, const gsl_vector *origin);

const gsl_vector *
gnn_line_get_origin (gnn_line *line);

gnn_grad *
gnn_line_get_grad (gnn_line *line);

int
gnn_line_pats (gnn_line *line,
                 double alpha, gnn_line_eval flag, size_t s, size_t n);

int
gnn_line_all (gnn_line *line, double alpha, gnn_line_eval flag);



#endif /* _GNN_EVALUATION_H_ */

---