---

gnn_trainer.h File Reference

#include "gnn_evaluation.h"

Include dependency graph for gnn_trainer.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	_gnn_trainer
Typedefs
typedef _gnn_trainer	gnn_trainer
	The datatype for trainer reset functions.
typedef int(*	gnn_trainer_reset_type )(gnn_trainer *trainer)
	The datatype for trainer reset functions.
typedef int(*	gnn_trainer_train_type )(gnn_trainer *trainer)
	The datatype for trainer train functions.
typedef void(*	gnn_trainer_destroy_type )(gnn_trainer *trainer)
	The datatype for trainer destroy functions.
Functions
const char *	gnn_trainer_get_type (gnn_trainer *trainer)
	Get the trainer's type.
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)
	Initializes a gnn_trainer : Trainers for Models. structure.
void	gnn_trainer_destroy (gnn_trainer *trainer)
	Destroys the trainer.
int	gnn_trainer_reset (gnn_trainer *trainer)
	Resets the trainer.
double	gnn_trainer_train (gnn_trainer *trainer)
	Trains the node.
gnn_dataset *	gnn_trainer_get_dataset (gnn_trainer *trainer)
	Get the dataset.
gnn_node *	gnn_trainer_get_node (gnn_trainer *trainer)
	Get the model.
gnn_criterion *	gnn_trainer_get_criterion (gnn_trainer *trainer)
	Get the criterion.
int	gnn_trainer_batch_set_size (gnn_trainer *trainer, size_t size)
	Set the size for minibatches.
size_t	gnn_trainer_batch_get_size (gnn_trainer *trainer)
	Get the size of the minibatches.
size_t	gnn_trainer_get_pattern_index (gnn_trainer *trainer)
	Returns the index of the next minibatch.
size_t	gnn_trainer_get_epoch (gnn_trainer *trainer)
	Get the number of the current epoch.
double	gnn_trainer_get_epoch_cost (gnn_trainer *trainer)
	Get the mean cost.
gnn_grad *	gnn_trainer_batch_get_grad (gnn_trainer *trainer)
	Returns a pointer to the internal Evaluations. buffer.
double	gnn_trainer_batch_get_e (gnn_trainer *trainer)
	Returns the last evaluated batch's mean error.
gsl_vector *	gnn_trainer_batch_get_dx (gnn_trainer *trainer)
	Returns the last batch's evaluated gradient dx.
gsl_vector *	gnn_trainer_batch_get_dw (gnn_trainer *trainer)
	Returns the last batch's evaluated gradient dw.
int	gnn_trainer_batch_process (gnn_trainer *trainer)
	Processes a batch.
int	gnn_trainer_batch_next (gnn_trainer *trainer)
	Moves onto the next batch.

---

Function Documentation

gsl_vector* gnn_trainer_batch_get_dw (  gnn_trainer *    trainer )

This function returns a the last evaluated batch's mean gradient with respect to its parameters . The returned vector can be freely accessed and its values modified, but it should not be freed. Parameters: trainer  A pointer to a gnn_trainer : Trainers for Models.. Returns: Returns . Definition at line 671 of file gnn_trainer.c.

gsl_vector* gnn_trainer_batch_get_dx (  gnn_trainer *    trainer )

This function returns a the last evaluated batch's mean gradient with respect to its inputs . The returned vector can be freely accessed and its values modified, but it should not be freed. Parameters: trainer  A pointer to a gnn_trainer : Trainers for Models.. Returns: Returns . Definition at line 652 of file gnn_trainer.c.

double gnn_trainer_batch_get_e (  gnn_trainer *    trainer )

This function returns a the last evaluated batch's mean error . Parameters: trainer  A pointer to a gnn_trainer : Trainers for Models.. Returns: Returns . Definition at line 633 of file gnn_trainer.c.

gnn_grad* gnn_trainer_batch_get_grad (  gnn_trainer *    trainer )

This function returns a pointer to the internal error and gradients evaluation buffer. Parameters: trainer  A pointer to a gnn_trainer : Trainers for Models.. Returns: Returns a pointer to the Evaluations.. Definition at line 618 of file gnn_trainer.c.

size_t gnn_trainer_batch_get_size (  gnn_trainer *    trainer )

This function returns a strictly positive number corresponding to the size of the minibatches that are processed upon a call of gnn_trainer_train. Parameters: trainer  A pointer to a gnn_trainer : Trainers for Models.. Returns: Returns the size of the minibatches. Definition at line 534 of file gnn_trainer.c.

int gnn_trainer_batch_next (  gnn_trainer *    trainer )

This function moves to the next batch. That is, if sets the trainers internal state to prepare to process the next batch. If the end of the dataset is reached, then the next epoch is initiated, the mean cost info cleared, the dataset reset. This function is very handy when implementing your own trainers. It should be used in conjunction with gnn_trainer_batch_process. Parameters: trainer  A pointer to a gnn_trainer : Trainers for Models.. Returns: Returns 0 if suceeded. Definition at line 730 of file gnn_trainer.c.

int gnn_trainer_batch_process (  gnn_trainer *    trainer )

This function processes the current minibatch of patterns, computing the batch's mean cost and its gradients and . They can be retrived afterthen by invoking gnn_trainer_batch_get_e gnn_trainer_batch_get_dx gnn_trainer_batch_get_dw gnn_trainer_get_epoch_cost Theese values are obtained by averaging over the batch's pattern. Several calls of this function will process the same minibatch. Only a call of gnn_trainer_batch_next moves onto the next one. This function is very handy when implementing your own trainers. It provides an easy way to obtain the gradient and handles the necessary field updates on the gnn_trainer : Trainers for Models.. Please refer to gnn_trainer : Trainers for Models. for details. Parameters: trainer  A pointer to a gnn_trainer : Trainers for Models.. Returns: Returns 0 if succeeded. Definition at line 704 of file gnn_trainer.c.

int gnn_trainer_batch_set_size (  gnn_trainer *    trainer, size_t    size )

This function sets the size of the minibatches that should be processed upon a call of gnn_trainer_train. This size should be stricly positive. Although it can be greather than the number of available patterns in the dataset, the effective minibatch will be smaller. Parameters: trainer  A pointer to a gnn_trainer : Trainers for Models.. size  The size for minibatches. Returns: Returns 0 if succeeded. Definition at line 505 of file gnn_trainer.c.

void gnn_trainer_destroy (  gnn_trainer *    trainer )

This function destroys the gnn_trainer : Trainers for Models. by calling the installed destructor function for the trainer type and by freeing the gnn_trainer : Trainers for Models.'s structure. It doesn't destroy the node, nor the criterion, nor the dataset. They should be destroyed independently. Parameters: trainer  A pointer to a gnn_trainer : Trainers for Models.. Definition at line 365 of file gnn_trainer.c.

gnn_criterion* gnn_trainer_get_criterion (  gnn_trainer *    trainer )

This function returns a pointer to the criterion that the trainer uses for training. Parameters: trainer  A pointer to a gnn_trainer : Trainers for Models.. Returns: Returns a pointer to a gnn_criterion : Basic Criterion Function.. Definition at line 484 of file gnn_trainer.c.

gnn_dataset* gnn_trainer_get_dataset (  gnn_trainer *    trainer )

This function returns a pointer to the dataset that the trainer uses for training. Parameters: trainer  A pointer to a gnn_trainer : Trainers for Models.. Returns: Returns a pointer to a gnn_dataset : Datasets for Training.. Definition at line 449 of file gnn_trainer.c.

size_t gnn_trainer_get_epoch (  gnn_trainer *    trainer )

This function returns the number of the current epoch. Parameters: trainer  A pointer to a gnn_trainer : Trainers for Models.. Returns: Returns the number of the current epoch. Definition at line 569 of file gnn_trainer.c.

double gnn_trainer_get_epoch_cost (  gnn_trainer *    trainer )

This function returns the mean cost of the patterns presented in the current epoch. That is, if the patterns have been evaluated in the current epoch, then the value where is the weight of the -th pattern, will be returned. It is important to note that this value considers also the last evaluated minibatch's cost. Parameters: trainer  A pointer to a gnn_trainer : Trainers for Models.. Returns: Returns the weighted sum . Definition at line 593 of file gnn_trainer.c.

gnn_node* gnn_trainer_get_node (  gnn_trainer *    trainer )

This function returns a pointer to the model that the trainer trains. Parameters: trainer  A pointer to a gnn_trainer : Trainers for Models.. Returns: Returns a pointer to a gnn_node. Definition at line 466 of file gnn_trainer.c.

size_t gnn_trainer_get_pattern_index (  gnn_trainer *    trainer )

This function returns the index of the first pattern in the minibatch to be processed. Parameters: trainer  A pointer to a gnn_trainer : Trainers for Models.. Returns: Returns the index of the next pattern. Definition at line 552 of file gnn_trainer.c.

const char* gnn_trainer_get_type (  gnn_trainer *    trainer )

This function returns a string which contains the name of the trainer's type. The string should not be modified. Parameters: trainer  A pointer to a gnn_trainer : Trainers for Models.. Returns: Returns a pointer to the trainer's own type string. Definition at line 187 of file gnn_trainer.c.

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 )

This function initializes a gnn_trainer : Trainers for Models. structure by setting its internal fields adecuately. Every extension to the gnn_trainer : Trainers for Models. structure should have a constructor that calls this function to: define the trainer's type, set the model to be trained (the node), set the criterion to be used, set the dataset with the patterns to be used during training, install the type-specific functions for "reset", "train" and "destroy" All arguments are mandatory, except for the "reset" and the "destroy" functions: if the are specified as NULL, then the defaults are installed instead (see gnn_trainer : Trainers for Models. and gnn_trainer : Trainers for Models.). The associated sizes should match. That is, the input pattern's sizes contained in the dataset should corresponde to the node's input size. Likewise, the output pattern's sizes should match with the node's output size and the criterion's size. The following example should clarify its use. Suppose you want to create a new trainer type, called "my_trainer". You have already implemented the two of the needed functions, "my_trainer_reset", "my_trainer_train". Actually, your special training function does not need any additional data, and so the destructor isn't needed. Then, the following code could be a possible implementation of the constructor: gnn_trainer * my_trainer_new (gnn_node *model, gnn_criterion *crit, gnn_dataset *data) { int status; my_trainer *t; // this is just an extension of gnn_trainer gnn_trainer *tview; // points to the same structure, but uses another // view // alloc space t = (my_trainer *) malloc (sizeof (*t)); if (t == NULL) print_error_message_and_return_error_code (); // cast to a gnn_trainer tview = (gnn_trainer *) t; // initialize status = gnn_trainer_init (tview, "my_trainer", model, crit, data, my_trainer_reset, my_trainer_reset, NULL); if (status) print_error_message_and_return_error_code (); // finish initialization ... return tview; } Parameters: trainer  A pointer to a gnn_trainer : Trainers for Models.. type  A string to the typename. It will be duplicated. node  A pointer to a gnn_node. crit  A pointer to a gnn_criterion : Basic Criterion Function.. data  A pointer to a gnn_data. reset  A pointer to the "reset" function (or NULL). train  A pointer to the "train" function. destroy  A pointer to the "destroy" function (or NULL). Returns: Returns 0 if initialization succeeded. Definition at line 271 of file gnn_trainer.c.

int gnn_trainer_reset (  gnn_trainer *    trainer )

This function resets the trainer, i.e. the error is cleared, the epoch reset, the pattern iterator set to the first pattern, etc. Parameters: trainer  A pointer to a gnn_trainer : Trainers for Models.. Returns: Returns 0 if suceeded. Definition at line 391 of file gnn_trainer.c.

double gnn_trainer_train (  gnn_trainer *    trainer )

This function executes a full iteration of the training algorithm on the node. In this context, an iteration consists of presenting a batch of patterns to the node and adjust its parameters accordingly. Every call to this function presents the next patterns until the end is reached. The last batch will be of smaller if the number of total patterns is not a multiple of the size of the batches. If the end is reached, then the trainer goes to the next epoch and the dataset is automatically reset. Parameters: trainer  A pointer to a gnn_trainer : Trainers for Models.. Returns: Returns the mean value of the (by the criterion) computed cost for the current epoch. Definition at line 426 of file gnn_trainer.c.

---