---

gnn_memory_input.c

Go to the documentation of this file.

/***************************************************************************
 *  @file gnn_memory_input.c
 *  @brief Input Set Residing in Memory Implementation.
 *
 *  @date   : 21-09-03 22: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_memory_input_doc gnn_memory_input : Memory Input Samples.
 * @ingroup gnn_input_doc
 * @brief Input sample sets that reside in memory.
 *
 * The \ref gnn_memory_input samples set stores its samples in memory. It has
 * a matrix, where the samples are stored row-wise.
 *
 * A \ref gnn_memory_input can be build directly providing the necessary
 * matrix using the \ref gnn_memory_input_new_from_matrix. Alternatively,
 * the matrix can be loaded using the \ref gnn_memory_input_new_from_file.
 */



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

#include "gnn_utilities.h"
#include "gnn_memory_input.h"



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

/**
 * @brief The datatype for memory inputs.
 * @ingroup gnn_memory_input_doc
 *
 * This is the datatype for memory inputs. It extends the basic
 * \ref gnn_input structure to include the additional pointer
 * to the samples matrix, and a vector view.
 */
typedef struct _gnn_memory_input gnn_memory_input;

struct _gnn_memory_input
{
    gnn_input        set;     /**< Set \ref gnn_input                  */
    gsl_matrix      *matrix;  /**< A pointer to the input patterns.    */
    gsl_vector_view  v;       /**< A view to the last required sample. */
};

static const gsl_vector *
gnn_memory_input_get (gnn_input *set, size_t k);

static void
gnn_memory_input_destroy (gnn_input *set);



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

/**
 * @brief The "get" function for a memory input set.
 * @ingroup gnn_memory_input_doc
 *
 * This function is returns the k-th pattern in the set.
 *
 * @param  set   A pointer to a \ref gnn_memory_input.
 * @param  k      The index of the pattern to be retrieved.
 * @return A pointer to the sample vector.
 */
static const gsl_vector *
gnn_memory_input_get (gnn_input *set, size_t k)
{
    gnn_memory_input *mset;

    assert (set != NULL);

    /* get memory dataset view */
    mset = (gnn_memory_input *) set;

    /* check index */
    if (k < 0 || mset->matrix->size1 <= k)
    {
        GSL_ERROR_VAL ("pattern index out of bounds", GSL_EINVAL, NULL);
    }

    /* get pattern views */
    mset->v = gsl_matrix_row (mset->matrix, k);

    return &(mset->v.vector);
}

/**
 * @brief Destroy function.
 * @ingroup gnn_memory_input_doc
 *
 * This is the \ref gnn_memory_input destroy function.
 * @param set A pointer to a \ref gnn_memory_input dataset.
 */
static void
gnn_memory_input_destroy (gnn_input *set)
{
    gnn_memory_input *mset;

    assert (set != NULL);

    /* get memory dataset view */
    mset = (gnn_memory_input *) set;

    /* free matrices and the weight vector */
    if (mset->matrix != NULL)
        gsl_matrix_free (mset->matrix);
}



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

/**
 * @brief Builds an input set from a matrix.
 * @ingroup gnn_memory_input_doc
 *
 * This function creates a new \ref gnn_memory_input from a matrix,
 * where the samples are stored row-wise. That is, each row should
 * contain a different sample, and each column corresponds to a different
 * sample's component.
 *
 * @param  m The sample matrix.
 * @return Returns a pointer to a new \ref gnn_memory_input set.
 */
gnn_input *
gnn_memory_input_new_from_matrix (gsl_matrix *m)
{
    size_t P;
    size_t n;
    int    status;
    gnn_input *set;
    gnn_memory_input *mset;

    assert (m != NULL);

    /* alloc memory for input set */
    mset = (gnn_memory_input *) malloc (sizeof (gnn_memory_input));

    /* get view as a input set */
    set = (gnn_input *) mset;

    /* get sizes */
    P = m->size1;
    n = m->size2;

    /* initialize */
    status = gnn_input_init (set,
                             P,
                             n,
                             NULL,
                             gnn_memory_input_get,
                             gnn_memory_input_destroy);
    if (status)
    {
        gnn_input_destroy (set);
        GSL_ERROR_VAL ("could not initialize gnn_memory_input",
                       GSL_EFAILED, NULL);
    }

    /* set fields */
    mset->matrix  = m;

    return set;
}

/**
 * @brief Builds a input set from a file.
 * @ingroup gnn_memory_input_doc
 *
 * This functions creates a new \ref gnn_memory_input from a file where the
 * samples are stored. Their elements should be in ASCII format separated
 * by blank spaces. Each row should start on a new line.
 *
 * Please read \ref gnn_memory_input_new_from_matrix for further details on
 * the needed format.
 *
 * @param  filename The filename of the input matrix.
 * @return Returns a pointer to a new \ref gnn_memory_input set.
 */
gnn_input *
gnn_memory_input_new_from_file (const char *filename)
{
    int status;
    gsl_matrix *matrix = NULL;

    assert (filename != NULL);

    /* load input and output matrices */
    matrix = gnn_matrix_load (filename);
    if (matrix == NULL)
    {
        GSL_ERROR_VAL ("could not load samples", GSL_EFAILED, NULL);
    }

    /* create and return dataset */
    return gnn_memory_input_new_from_matrix (matrix);
}

---