---

gnn_utilities.c

Go to the documentation of this file.

/***************************************************************************
 *  @file gnn_utilities.h
 *  @brief General \ref libgnn utilities.
 *  @defgroup gnn_utilities \ref libgnn general utility functions.
 *
 *  @date   : 06-08-03 09:34
 *  @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_utilities_doc Utilities Interface.
 * @ingroup  libgnn
 *
 * This module contains miscelaneous utilities, like vector operations not
 * available in the original GSL specification, access to an application-wide
 * random number generator, etc.
 *
 */
 
/******************************************/
/* Include Files                          */
/******************************************/

#include <time.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <gsl/gsl_block.h>
#include <assert.h>
#include <math.h>
#include "gnn_globals.h"
#include "gnn_utilities.h"

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

/**
 * @brief Get the global random number generator.
 * @ingroup gnn_utilities_doc
 *
 * This function returns a pointer to an application-wide GSL random number
 * generator. It allocates a new one if not defined yet.
 *
 * The type of the random number generator is given by the constant
 * \ref GNN_DEFAULT_RNG.
 *
 * Note: This function is not thread safe.
 *
 * @return A pointer to the random number generator.
 */
gsl_rng *
gnn_get_rng ()
{
    static gsl_rng * r = NULL;
    if (r == NULL)
    {
        r = gsl_rng_alloc(GNN_DEFAULT_RNG);
        gsl_rng_set (r, time (NULL));
    }
    return r;
}



/**
 * @brief Resize a vector
 * @ingroup gnn_utilities_doc
 *
 * This function resizes a vector and tries to preserve all posible values,
 * i.e.
 * \f[ \forall i=1,\ldots,m \quad v_i = w_i \f]
 * where \f$v=[v_1,\ldots,v_{n_1}]\f$ is the vector before and
 * \f$v=[w_1,\ldots,w_{n_2}]\f$ is the vector after resizing, and
 * \f$m = \min (n_1, n_2)\f$.
 *
 * @param vector   A vector.
 * @param new_size The new size (\f$n_2\f$ in the explanation above).
 * @return Returns 0 if succeeded.
 */
int
gnn_vector_resize (gsl_vector **vector, int new_size)
{
    gsl_vector *v = NULL;
    gsl_vector *w = NULL;
    
    v = *vector;

    /* build the new vector w if the size is > 0 */
    if (new_size > 0)
    {
        /* alloc blank vector */
        w = gsl_vector_calloc (new_size);
        assert (w != NULL);

        /* copy old values if any */
        if (v != NULL)
        {
            int min_size;
            gsl_vector_view v_view;
            gsl_vector_view w_view;

            min_size = GNN_MIN (v->size, w->size);
            v_view = gsl_vector_subvector (v, 0, min_size);
            w_view = gsl_vector_subvector (w, 0, min_size);

            gsl_vector_memcpy (&(w_view.vector), &(v_view.vector));
        }
    }

    /* destroy old vector if any */
    if (v != NULL)
    {
        assert (v->block != NULL);
        gsl_block_free (v->block);
    }
    
    *vector = w;

    return 0;
}

/**
 * @brief Compute the sum of the vector's elements.
 * @ingroup gnn_utilities_doc
 *
 * This function computes the sum of the vector's elements, that is:
 * \f[ \sum_{i=1}^n x_i \f]
 *
 * @param v A pointer to a vector of size \f$n\f$.
 * @return Returns the sum of its elements.
 */
int
gnn_vector_sum_elements (gsl_vector *v)
{
    size_t i;
    double s = 0.0;
    for (i=0; i<v->size; ++i)
        s += gsl_vector_get (v, i);
    return s;
}

/**
 * @brief Compute the euclidian distance between to vectors.
 * @ingroup gnn_utilities_doc
 *
 * This function computes the euclidian distance between to vectors, given
 * by:
 * \f[ \sqrt{ \sum_{i=1}^n (v_i - u_i)^2 } \f]
 *
 * @param v A pointer to a vector of size \f$n\f$.
 * @param u A pointer to a vector of size \f$n\f$.
 * @return Returns the distance.
 */
double
gnn_vector_euclidian_dist (const gsl_vector *v, const gsl_vector *u)
{
    size_t i;
    double vi, ui;
    double d = 0.0;

    for (i=0; i<v->size; ++i)
    {
        vi = v->data[i*v->stride];
        ui = u->data[i*u->stride];
        d  += (vi - ui) * (vi - ui);
    }
    return sqrt(d);
}

/**
 * @brief Compute matrix size from a stream.
 * @ingroup gnn_utilities_doc
 * @todo Make this function check for the integrity of the matrix.
 *
 * This function reads a stream until it reaches EOF, and makes an estimation
 * of the contained matrix size.
 *
 * @param stream A file stream.
 * @param m      A pointer to the variable to store the number of rows.
 * @param n      A pointer to the variable to store the number of columns.
 * @return Returns 0 if succeeded.
 */
int
gnn_matrix_check_sizes_from_stream (FILE *stream, size_t *m, size_t *n)
{
        int   i;
    int   j;
        char  buf[GNN_MAX_BUF + 1];
        char *tok;

    assert (stream != NULL);
    assert (m != NULL);
    assert (n != NULL);

        /* initialize sizes */
        *m = *n = 0;

        /* check for opened stream */
        if (stream == NULL)
                GSL_ERROR ("stream invalid", GSL_EINVAL);

        /* determine the size of the matrix */
        if (fgets (buf, GNN_MAX_BUF + 1, stream) != NULL)
        {
                if (strtok (buf, " \t\r\n") != NULL)
                        *n = 1;
                while (strtok (NULL, " \t\r\n") != NULL)
                        (*n)++;
        if (*n > 0)
                *m = 1;
                while (fgets (buf, GNN_MAX_BUF + 1, stream) != NULL)
                        (*m)++;
        }

    return 0;
}



/**
 * @brief Load a vector from a file.
 * @ingroup gnn_utilities_doc
 *
 * This function loads a vector from a file. It creates a gsl_vector of the
 * correct size.
 *
 * @param filename The file name from where the vector should be loaded.
 * @return A pointer to a new gsl_vector.
 */
gsl_vector *
gnn_vector_load (const char *filename)
{
        int   m;
        int   n;
    int   status;
        FILE *fp;
        gsl_vector *v;

        /* open file */
        fp = fopen (filename, "r");
        if (fp == NULL)
                GSL_ERROR_VAL ("could not open vector file.", GSL_EINVAL, NULL);

        /* determine the size of the matrix */
    status = gnn_matrix_check_sizes_from_stream (fp, &m, &n);
    if (status)
        GSL_ERROR_VAL ("error determining the size of the vector",
                       GSL_EFAILED, NULL);

        /* close file */
        fclose (fp);

        /* check sizes */
        if (n == 0 || m == 0)
                GSL_ERROR_VAL ("vector is empty", GSL_EINVAL, NULL);

    /* create and load vector */
        v  = gsl_vector_alloc (m * n);
        fp = fopen (filename, "r");
        if (fp == NULL)
                GSL_ERROR_VAL ("could not open vector file.", GSL_EINVAL, NULL);
        gsl_vector_fscanf (fp, v);
        fclose (fp);

    return v;
}

/**
 * @brief Saves a vector to a file.
 * @ingroup gnn_utilities_doc
 *
 * This function saves a vector to a file.
 *
 * @param filename The file name from where the vector should be loaded.
 * @param A        A gsl_vector which should be saved.
 * @return Returns 0 if suceeded.
 */
int
gnn_vector_save (const char *filename, gsl_vector *v)
{
    FILE *fp;

    /* open file and save vector */
        fp = fopen (filename, "w");
        if (fp == NULL)
        GSL_ERROR ("could not open file for output", GSL_EINVAL);
        gsl_vector_fprintf (fp, v, "%g");
        fclose (fp);

        return 0;
}

/**
 * @brief Load a matrix from a file.
 * @ingroup gnn_utilities_doc
 *
 * This function loads a matrix from a file. It creates a gsl_matrix of the
 * correct size.
 *
 * @param filename The file name from where the matrix should be loaded.
 * @return A pointer to a new gsl_matrix.
 */
gsl_matrix *
gnn_matrix_load (const char *filename)
{
        int   m;
        int   n;
    int   status;
        FILE *fp;
        gsl_matrix *A;

        /* open file */
        fp = fopen (filename, "r");
        if (fp == NULL)
                GSL_ERROR_VAL ("could not open matrix file.", GSL_EINVAL, NULL);

        /* determine the size of the matrix */
    status = gnn_matrix_check_sizes_from_stream (fp, &m, &n);
    if (status)
        GSL_ERROR_VAL ("error determining the size of the matrix",
                       GSL_EFAILED, NULL);

        /* close file */
        fclose (fp);

        /* check sizes */
        if (n == 0 || m == 0)
                GSL_ERROR_VAL ("matrix is empty", GSL_EINVAL, NULL);

    /* create and load matrix */
        A  = gsl_matrix_alloc (m, n);
        fp = fopen (filename, "r");
        if (fp == NULL)
                GSL_ERROR_VAL ("could not open matrix file.", GSL_EINVAL, NULL);
        gsl_matrix_fscanf (fp, A);
        fclose (fp);

    return A;
}

/**
 * @brief Saves a matrix to a file.
 * @ingroup gnn_utilities_doc
 *
 * This function saves a matrix to a file.
 *
 * @param filename The file name from where the matrix should be loaded.
 * @param A        A gsl_matrix which should be saved.
 * @return Returns 0 if suceeded.
 */
int
gnn_matrix_save (const char *filename, gsl_matrix *A)
{
    FILE *fp;
    
    /* open file and save matrix */
        fp = fopen (filename, "w");
        if (fp == NULL)
        GSL_ERROR ("could not open file for output", GSL_EINVAL);
        gsl_matrix_fprintf (fp, A, "%g");
        fclose (fp);
        
        return 0;
}

---