---

gnn_trainer.h

Go to the documentation of this file.

/***************************************************************************
 *  @file gnn_trainer.h
 *  @brief Trainer Header File.
 *
 *  @date   : 29-08-03 21:46
 *  @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_TRAINER_H_
#define _GNN_TRAINER_H_



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

#include "gnn_evaluation.h"



/******************************************/
/* Typedefs                               */
/******************************************/

/**
 * @brief The datatype for trainer reset functions.
 * @ingroup gnn_trainer_doc
 *
 * This is the datatype that contains the basic elements for the implementation
 * of a trainer. Every new type of trainer should extend this structure.
 */
typedef struct _gnn_trainer gnn_trainer;

/**
 * @brief The datatype for trainer reset functions.
 * @ingroup gnn_trainer_doc
 *
 * This is the datatype for the \ref gnn_trainer's "reset" function. These
 * functions are called by the \ref gnn_trainer_reset function. They should
 * reset the trainer's internal state, so that a new training procedure
 * can begin.
 */
typedef int (*gnn_trainer_reset_type) (gnn_trainer *trainer);

/**
 * @brief The datatype for trainer train functions.
 * @ingroup gnn_trainer_doc
 *
 * This function returns the sum of the patterns' costs.
 *
 * This is the datatype for the \ref gnn_trainer's "train" function. This
 * function is called by the \ref gnn_trainer_train function. Basically,
 * it should update the model's parameters in order to minimize the
 * criterion, using a minibatch of patterns, starting at "currpat". In order
 * to simplify the implementation, \ref libgnn provides the
 * \ref gnn_trainer_batch_process function, which processes a minibatch:
 * it returns mean cost of the so far evaluated patterns and the estimation
 * \f[ \frac{\partial \hat{E}}{\partial w} =
 *     \frac{ \sum_k p_k
 *            { \left . \frac{\partial E}{\partial w} \right | }_{x_k}
 *          }
 *          { \sum_k p_k } \f]
 * of the gradient, where the sums are taken for the patterns in the minibatch.
 * You can then use the returned gradient to update the model's parameters.
 * After that, don't forget to return the sum of the costs (which is returned
 * by \ref gnn_trainer_batch_process).
 */
typedef int (*gnn_trainer_train_type) (gnn_trainer *trainer);

/**
 * @brief The datatype for trainer destroy functions.
 * @ingroup gnn_trainer_doc
 *
 * This function is called by the \ref gnn_trainer_destroy function, and
 * should free all extra data that was allocated for the specific trainer
 * type. The \ref gnn_trainer data is handled automatically (and freed) by
 * \ref gnn_trainer_destroy, so only additional data should be freed
 * by implementations of this function type.
 */
typedef void (*gnn_trainer_destroy_type) (gnn_trainer *trainer);

struct _gnn_trainer
{
    const char    *type; /**< The type of the trainer.                        */
    
    gnn_node      *node; /**< A pointer to the node to be trained.            */
    gnn_criterion *crit; /**< A pointer to the criterion.                     */
    gnn_dataset   *data; /**< A pointer to the dataset.                       */
    
    size_t n;            /**< The size of the batches to be processed.        */
    size_t s;            /**< The number of the next pattern to be evaluated. */
    size_t epoch;        /**< The number of the current epoch.                */
    double sume;         /**< The sum of the epochs evaluated criterions.     */
    double sump;         /**< The sum of the patterns' weights viewed so far. */

    gnn_grad *grad;      /**< The internal batch gradients evaluation buffers.*/
    
    gnn_trainer_reset_type   reset;      /**< The "reset" function pointer.   */
    gnn_trainer_train_type   train;      /**< The "train" function pointer.   */
    gnn_trainer_destroy_type destroy;    /**< The "destroy" function pointer. */
};



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

const char *
gnn_trainer_get_type (gnn_trainer *trainer);

int
gnn_trainer_init (gnn_trainer             *trainer,
                  const char              *type,
                  gnn_node                *node,
                  gnn_criterion           *crit,
                  gnn_dataset             *data,
                  gnn_trainer_reset_type   reset,
                  gnn_trainer_train_type   train,
                  gnn_trainer_destroy_type destroy);

void
gnn_trainer_destroy (gnn_trainer *trainer);

int
gnn_trainer_reset (gnn_trainer *trainer);

double
gnn_trainer_train (gnn_trainer *trainer);


gnn_dataset *
gnn_trainer_get_dataset (gnn_trainer *trainer);

gnn_node *
gnn_trainer_get_node (gnn_trainer *trainer);

gnn_criterion *
gnn_trainer_get_criterion (gnn_trainer *trainer);


int
gnn_trainer_batch_set_size (gnn_trainer *trainer, size_t size);

size_t
gnn_trainer_batch_get_size (gnn_trainer *trainer);


size_t
gnn_trainer_get_pattern_index (gnn_trainer *trainer);

size_t
gnn_trainer_get_epoch (gnn_trainer *trainer);

double
gnn_trainer_get_epoch_cost (gnn_trainer *trainer);

gnn_grad *
gnn_trainer_batch_get_grad (gnn_trainer *trainer);

double
gnn_trainer_batch_get_e (gnn_trainer *trainer);

gsl_vector *
gnn_trainer_batch_get_dx (gnn_trainer *trainer);

gsl_vector *
gnn_trainer_batch_get_dw (gnn_trainer *trainer);

int
gnn_trainer_batch_process (gnn_trainer *trainer);

int
gnn_trainer_batch_next (gnn_trainer *trainer);



#endif /* _GNN_TRAINER_H_ */

---