---

gnn_phandle.c

Go to the documentation of this file.

/***************************************************************************
 *  @file  gnn_phandle.c
 *  @brief gnn_phandle Implementation.
 *
 *  @date   : 15-08-03 01:44
 *  @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.
 */



/**
 * @brief Handle for managing a set of parameters.
 * @defgroup gnn_phandle_doc gnn_phandle : A Handle for Parameters.
 * @ingroup  gnn_node_doc
 *
 * The \ref gnn_phandle provides a data structure for encapsulating the
 * necessary information for handling shareable parameters. A \ref gnn_phandle
 * knows about the number of free (not fixed) parameters, its values, and
 * if they are actually used.
 *
 * The following scheme shows a \ref gnn_phandle. It is important to note that:
 * - A reference counter manages the number of clients that are using the
 *   the parameter handle. If this counter decreases to zero, the handle is
 *   deallocated with its three vectors. Every client should register the use
 *   with \ref gnn_phandle_ref and unregister with \ref gnn_phandle_unref.
 *
 * <img src="images/gnn_phandle1.png">
 *
 * - Three vectors are used to store the parameter values, the gradient,
 *   and the frozen flags.
 * - Additional fields keep track of the number of parameters and the
 *   number of free (not frozen) paramters.
 *
 * The manipulation of a handle is simple. The handle's vectors w, dw and
 * f can be accessed freely through \ref gnn_phandle_get_w,
 * \ref gnn_phandle_get_dw and \ref gnn_phandle_get_f respectivelly. After
 * changing them, call \ref gnn_phandle_update. This will update the fields
 * to reflect the changes that have been made.
 *
 * Also, the \ref gnn_pbundle interface can be used to manipulate a set
 * of related parameter handles.
 *
 * @warning Currently, the handling of parameters isn't thread safe.
 */



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

#include <assert.h>
#include <gsl/gsl_vector.h>
#include <gsl/gsl_errno.h>
#include "gnn_phandle.h"
#include "chunkallocator.h"



/******************************************/
/* Global variables                       */
/******************************************/

/**
 * @brief The internal memory chunk allocator for parameter handles.
 * @ingroup gnn_phandle_doc
 *
 * This variable points to the parameter handle memory allocator. A first
 * call to \ref gnn_phandle_new instanciates it.
 */
static chunkallocator *_phallocator = NULL;



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

static void
gnn_phandle_destroy (gnn_phandle *ph);

static int
gnn_vector_use_flags (gsl_vector *v, const gsl_vector_int *f);

static int
gnn_vector_int_count_frozen_flags (const gsl_vector_int *f);



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

/**
 * @brief Destroys a parameter handle.
 * @ingroup gnn_phandle_doc
 *
 * This static function deallocates the parameter handle's memory, including
 * its referenced data blocks for parameters. It can't be called publically,
 * because it is only triggered (by \ref gnn_phandle_unref) when the reference
 * counter falls to zero.
 *
 * @param ph The parameter handle to be deallocated.
 */
static void
gnn_phandle_destroy (gnn_phandle *ph)
{
    if (ph == NULL)
        return;

    /* free vectors if any */
    if (ph->w  != NULL)
        gsl_vector_free (ph->w);
    if (ph->dw != NULL)
        gsl_vector_free (ph->dw);
    if (ph->f  != NULL)
        gsl_vector_int_free (ph->f);

    /* free handle */
    chunkallocator_free (_phallocator, ph);
}

/**
 * @brief Set the frozen parameters to zero.
 * @ingroup gnn_phandle_doc
 *
 * This function takes a real vector and an integer vector. The integer vector
 * should have binary {0,1} values, that are used as frozen flags. All elements
 * of v whose corresponding frozen flag in f is non-zero is set to zero.
 *
 * @param  v A real vector.
 * @param  f An integer vector of binary values.
 * @return 0 if succeeded.
 */
static int
gnn_vector_use_flags (gsl_vector *v, const gsl_vector_int *f)
{
    int size;
    int i;
    double *vptr;
    int    *fptr;

    assert (v != NULL);
    assert (f != NULL);
    assert (v->size == f->size);

    /* copy values */
    size = v->size;
    for (i=0, vptr=v->data, fptr=f->data; i<v->size; i++, vptr++, fptr++)
        if (*fptr) *vptr = 0.0;

    return 0;
}

/**
 * @brief Counts the amount of frozen flags.
 * @ingroup gnn_phandle_doc
 *
 * This function takes an integer vector with binary values {0,1} and counts
 * the amount of non-zero values, which correspond to frozen flags.
 *
 * @param  f An integer vector of binary values.
 * @return 0 if succeeded.
 */
static int
gnn_vector_int_count_frozen_flags (const gsl_vector_int *f)
{
    int i;
    int *fptr;
    int count;
    int size;

    assert (f != NULL);

    /* count frozen flags */
    size = f->size;
    for (i=0, fptr=f->data, count=0; i<size; i++, fptr++)
        if (*fptr) count++;
    return count;
}



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

/**
 * @brief Creates a new parameter handle.
 * @ingroup gnn_phandle_doc
 *
 * This function allocates a new parameter handle for the given number of
 * parameters. It creates the underlying blocks of parameters, parameter
 * gradients and freeze flags. It's fields are appropiately initialized.
 *
 * Of course, the number of parameters can perfectly be zero. In this case,
 * the creation of the underlying data blocks is ommitted.
 *
 * @param size The number of parameters that the handle should actually handle.
 * @return A pointer to a new parameter handle.
 */
gnn_phandle *
gnn_phandle_new (size_t size)
{
    gnn_phandle *ph;
    
    assert (size >= 0);
    
    /* create chunkallocator */
    if (_phallocator == NULL)
    {
        _phallocator = chunkallocator_new (sizeof (gnn_phandle));
        if (_phallocator == NULL)
            GSL_ERROR_VAL ("could not create phandle chunkallocator",
                                                             GSL_ENOMEM, NULL);
    }
    
    /* create phandle */
    ph = (gnn_phandle *) chunkallocator_alloc (_phallocator);
    if (ph == NULL)
        GSL_ERROR_VAL ("could not allocate phandle", GSL_ENOMEM, NULL);

    /* set fields */
    ph->l        = size;
    ph->free     = size;
    ph->modified = 0;
    ph->w        = NULL;
    ph->dw       = NULL;
    ph->f        = NULL;
    ph->rc       = 1;
    
    /* if there are params, then create them */
    if (size > 0)
    {
        /* allocate vectors */
        ph->w  = gsl_vector_alloc (size);
        ph->dw = gsl_vector_alloc (size);
        ph->f  = gsl_vector_int_calloc (size);
        if ((ph->w == NULL) || (ph->dw == NULL) || (ph->f == NULL))
        {
            gnn_phandle_destroy (ph);
            GSL_ERROR_VAL ("could not allocate phandle vectors",
                                                             GSL_ENOMEM, NULL);
        }
    }
    
    return ph;
}

/**
 * @brief Unreferences a parameter handle.
 * @ingroup gnn_phandle_doc
 *
 * This function decreases the reference count of the parameter handle. It
 * should be called when the parameters aren't used anymore.
 *
 * If the reference count drops to zero, then the associated parameters
 * aren't used by anyone, triggering the real deallocation of the handle.
 *
 * @param ph The parameter handle to be unreferenced.
 */
int
gnn_phandle_unref (gnn_phandle *ph)
{
    /* check if there is a handle */
    if (ph == NULL)
        GSL_ERROR ("cannot unref NULL phandle", GSL_EINVAL);

    /* decrease reference counter */
    ph->rc--;

    /* free if zero */
    if (ph->rc == 0)
        gnn_phandle_destroy (ph);
    
    return 0;
}

/**
 * @brief References a parameter handle.
 * @ingroup gnn_phandle_doc
 *
 * This function increases the reference count of the parameter handle. It
 * should be called when the parameters are being shared.
 *
 * @param ph The parameter handle to be referenced.
 */
int
gnn_phandle_ref (gnn_phandle *ph)
{
    /* check if there is a handle */
    if (ph == NULL)
        GSL_ERROR ("cannot reference NULL phandle", GSL_EINVAL);

    /* increase reference counter */
    ph->rc++;
    
    return 0;
}

/**
 * @brief Returns the total number of parameters.
 * @ingroup gnn_phandle_doc
 *
 * @param ph A pointer to a parameter handle.
 * @return The number of total (free + frozen) parameters.
 */
size_t
gnn_phandle_get_size (gnn_phandle *ph)
{
    assert (ph != NULL);
    return ph->l;
}

/**
 * @brief Returns the number of free parameters.
 * @ingroup gnn_phandle_doc
 *
 * @param ph A pointer to a parameter handle.
 * @return The number of free (not fixed) parameters.
 */
size_t
gnn_phandle_get_free (gnn_phandle *ph)
{
    assert (ph != NULL);
    return ph->free;
}

/**
 * @brief Returns a pointer to the internal parameter vector.
 * @ingroup gnn_phandle_doc
 *
 * This function returns a pointer to the internal parameter vector \f$w\f$.
 * The user can modify its values at will. After changes are made, the
 * \ref gnn_phandle_update function should be called to recompute the
 * auxiliary information and reflect the changes.
 *
 * @param ph The parameter handle to be referenced.
 * @return A pointer to the parameter vector.
 */
gsl_vector *
gnn_phandle_get_w (gnn_phandle *ph)
{
    assert (ph != NULL);
    return ph->w;
}

/**
 * @brief Returns a pointer to the internal parameter gradient.
 * @ingroup gnn_phandle_doc
 *
 * This function returns a pointer to the internal parameter gradient
 * \f$\frac{\partial E}{\partial w}\f$.
 * The user can modify its values at will. After changes are made, the
 * \ref gnn_phandle_update function should be called to recompute the
 * auxiliary information and reflect the changes.
 *
 * @param ph The parameter handle to be referenced.
 * @return A pointer to the parameter gradient.
 */
gsl_vector *
gnn_phandle_get_dw (gnn_phandle *ph)
{
    assert (ph != NULL);
    
    /* set update flag */
    ph->modified |= PHandleUseFlags;

    return ph->dw;
}

/**
 * @brief Returns a pointer to the internal frozen flags.
 * @ingroup gnn_phandle_doc
 *
 * This function returns a pointer to the internal frozen flags \f$f\f$.
 * The user can modify its values at will. After changes are made, the
 * \ref gnn_phandle_update function should be called to recompute the
 * auxiliary information and reflect the changes.
 *
 * It should be remembered that the vector's element have binary values.
 * That is, 0 means "free" parameter, 1 means "frozen" or "fixed" parameter.
 *
 * @param ph The parameter handle to be referenced.
 * @return A pointer to the frozen flags.
 */
gsl_vector_int *
gnn_phandle_get_f (gnn_phandle *ph)
{
    assert (ph != NULL);

    /* set update flag */
    ph->modified |= PHandleCountFlags;

    return ph->f;
}

/**
 * @brief Updates the handle's fields.
 * @ingroup gnn_phandle_doc
 *
 * This function should be called after changes have made to the handle's
 * vectors w, dw or f, to update the fields and check for consistency.
 *
 * @note Only the necessary values are updated.
 *
 * @param ph The parameter handle to be updated.
 * @return 0 if succeeded.
 */
int
gnn_phandle_update (gnn_phandle *ph)
{
    assert (ph != NULL);

    if (ph->l > 0)
    {
        /* Count number of flags */
        if (ph->modified & PHandleCountFlags)
        {
            ph->free = ph->l - gnn_vector_int_count_frozen_flags (ph->f);
            ph->modified &= ~PHandleCountFlags;
        }

        /* Use the flags and set dw to zero where necessary */
        if (ph->modified & PHandleUseFlags)
        {
            gnn_vector_use_flags (ph->dw, ph->f);
            ph->modified &= ~PHandleUseFlags;
        }
    }

    return 0;
}

---