---

gnn_memory_output.c

Go to the documentation of this file.

/***************************************************************************
 *  @file gnn_memory_output.c
 *  @brief Input Set Residing in Memory Implementation.
 *
 *  @date   : 22-09-03 21:22
 *  @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_output_doc gnn_memory_output : Memory Output Samples.
 * @ingroup gnn_output_doc
 * @brief Output sample sets that reside in memory.
 *
 * The \ref gnn_memory_output samples set stores its samples in memory.
 * Internally, it contains a matrix, where the output samples are stored
 * row-wise, so the matrix can be retrieved.
 *
 * A \ref gnn_memory_output can be build directly providing a matrix of the
 * required size using the \ref gnn_memory_output_new_from_matrix.
 * Alternatively, it can be built just by indicating the number of outputs
 * that it should be able to store, and their size.
 */



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

#include "gnn_utilities.h"
#include "gnn_memory_output.h"



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

/**
 * @brief The datatype for memory outputs.
 * @ingroup gnn_memory_output_doc
 *
 * This is the datatype for memory outputs. It extends the basic
 * \ref gnn_output structure to include the additional pointer
 * to the output samples matrix, and a vector view.
 */
typedef struct _gnn_memory_output gnn_memory_output;

struct _gnn_memory_output
{
    gnn_output       set;     /**< The underlying \ref gnn_input structure. */
    gsl_matrix      *matrix;  /**< A pointer to the outputs.                */
    gsl_vector_view  v;       /**< A view to the last stored sample.        */
};

static int
gnn_memory_output_put (gnn_output *set, size_t k, const gsl_vector *v);

static void
gnn_memory_output_destroy (gnn_output *set);



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

/**
 * @brief The "put" function for a memory output set.
 * @ingroup gnn_memory_output_doc
 *
 * This function stores the k-th pattern in the set.
 *
 * @param  set A pointer to a \ref gnn_memory_output.
 * @param  k   The index of the pattern to be stored.
 * @param  v   A pointer to the output vector to be stored.
 * @return Returns 0 if suceeded.
 */
static int
gnn_memory_output_put (gnn_output *set, size_t k, const gsl_vector *v)
{
    gnn_memory_output *mset;

    assert (set != NULL);

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

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

    /* get pattern views */
    mset->v = gsl_matrix_row (mset->matrix, k);
    
    /* copy output */
    gsl_vector_memcpy (&(mset->v.vector), v);

    return 0;
}

/**
 * @brief Destroy function.
 * @ingroup gnn_memory_output_doc
 *
 * This is the \ref gnn_memory_output destroy function.
 * @param set A pointer to a \ref gnn_memory_output dataset.
 */
static void
gnn_memory_output_destroy (gnn_output *set)
{
    gnn_memory_output *mset;

    assert (set != NULL);

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

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



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

/**
 * @brief Builds an output set for required sizes.
 * @ingroup gnn_memory_output_doc
 *
 * This function creates a new \ref gnn_memory_output that should be able
 * to store the given number of patterns, where the sample's size is also
 * given.
 *
 * @param  size The number of patterns to be stored by the output.
 * @param  n    The size of an output sample vector.
 * @return Returns a pointer to a new \ref gnn_memory_output set.
 */
gnn_output *
gnn_memory_output_new (size_t size, size_t n)
{
    int status;
    gsl_matrix *matrix;

    /* check for valid sizes */
    if (size < 1)
    {
        GSL_ERROR_VAL ("set size should be stricly positive", GSL_EINVAL, NULL);
    }
    if (n < 1)
    {
        GSL_ERROR_VAL ("vector size should be stricly positive",
                       GSL_EINVAL, NULL);
    }

    /* allocate matrix */
    matrix = gsl_matrix_alloc (size, n);
    if (matrix == NULL)
    {
        GSL_ERROR_VAL ("could not allocate internal matrix",
                       GSL_ENOMEM, NULL);
    }

    return gnn_memory_output_new_from_matrix (matrix);
}

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

    assert (m != NULL);

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

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

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

    /* initialize */
    status = gnn_output_random_access_init (set, P, n,
                 NULL, gnn_memory_output_put, gnn_memory_output_destroy);
    if (status)
    {
        gnn_output_destroy (set);
        GSL_ERROR_VAL ("could not initialize gnn_memory_output",
                       GSL_EFAILED, NULL);
    }

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

    return set;
}

/**
 * @brief Returns the set's internal matrix.
 * @ingroup gnn_memory_output_doc
 *
 * This function returns a pointer to the set's internal matrix. This matrix
 * stores the output vectors row-wise.
 *
 * @param  set A pointer to a \ref gnn_output.
 * @return Returns a pointer to the internal matrix.
 */
const gsl_matrix *
gnn_memory_output_get_matrix (gnn_output *set)
{
    gnn_memory_output *mset;

    assert (set != NULL);

    mset = (gnn_memory_output *) set;
    return mset->matrix;
}

/**
 * @brief Saves the outputs to a file.
 * @ingroup gnn_memory_output_doc
 *
 * This function saves the outputs stored in the matrix to a file, in
 * plain ASCII format.
 *
 * @param  set      A pointer to the output set.
 * @param  filename A string with the name of the output file.
 * @return Returns 0 if succeeded.
 */
int
gnn_memory_output_save (gnn_output *set, const char *filename)
{
    int status;
    gnn_memory_output *mset;

    assert (set != NULL);

    mset = (gnn_memory_output *) set;
    
    status = gnn_matrix_save (filename, mset->matrix);

    
    return status;
}

---