---

gnn_pbundle.c

Go to the documentation of this file.

/***************************************************************************
 *  @file  gnn_pbundle.c
 *  @brief gnn_pbundle Implementation.
 *
 *  @date   : 15-08-03 02:13
 *  @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 Provides a unified view of multiple parameters.
 * @defgroup gnn_pbundle_doc gnn_pbundle : A Unified View of Parameter Sets.
 * @ingroup  gnn_node_doc
 *
 * The parameter bundle is a special datatype that holds the information of
 * multiple parameter handles. It hides its underlying compositional structure,
 * providing an unified access to the handles as it were a single parameter
 * vector.
 *
 * A bundle that starts with zero elements can be create with
 * \ref gnn_pbundle_new, and more \ref gnn_phandle can be
 * added with \ref gnn_pbundle_insert and removed with \ref gnn_pbundle_remove
 * functions. The bundle keeps track of the amount of times every handle has
 * been added.
 *
 * <img src="images/gnn_pbundle1.png">
 *
 * A bundle can me augmented with another bundle's element by invoking
 * the \ref gnn_pbundle_join function. To detach elements, use the
 * \ref gnn_pbundle_detach function. Each of this functions keep the
 * multiplicity counters consistent.
 *
 * By calling the \ref gnn_phandle_get function, you can retrieve the
 * bundle's parameter vector \f$w\f$, which is the ordered concatenation
 * of the \f$N\f$ subparameters of each of the handles:
 * \f[w = [w_1, w_2, \ldots, w_N]^t\f]
 * where \f$w_i\f$ is the \f$i\f$-th handle's parameter vector. The parameter's
 * total size is \ref gnn_pbundle_get_size.
 *
 * <img src="images/gnn_pbundle2.png">
 *
 * The specific order in which the handles are stored in the \ref gnn_pbundle
 * cannot be manipulated directly. It depends of the way the bundle was
 * built, i.e. on the order in which the elements were inserted. But, two
 * different bundles that were built by applying the same operations in the
 * same order are assured to be equal.
 *
 * The parameter \f$w\f$ can be accessed and manipulated using a set of
 * provided functions. Similarly, a set of analogous functions is available
 * for the gradient \f$\frac{\partial E}{\partial w}\f$ and the frozen flags
 * \f$f\f$.
 *
 * @note The inmplementation of bundles and handles is intimately related
 *       for efficiency reasons. Every change in one of both should be revised
 *       carefully.
 *
 * @warning The use of parameter bundles isn't thread safe at the time.
 */



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

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


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

/**
 * @brief The internal \ref gnn_pbundle memory chunk allocator.
 * @ingroup gnn_pbundle_doc
 *
 * This static variable holds the internal memory chunk allocator for the
 * \ref gnn_pbundle type. Every single parameter bundle element is allocated
 * using this memory manager for efficiency.
 *
 * Because of its application-wide nature, the memory allocation scheme
 * isn't thread safe by now.
 */
static chunkallocator *_ca = NULL;



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

/**
 * @brief Creates a new \ref gnn_pbundle.
 * @ingroup gnn_pbundle_doc
 *
 * This function allocates a new \ref gnn_pbundle with its values initialized
 * to zero parameter handles / elements.
 *
 * Implementation Note: The memory is managed (for efficiency) by a memory
 * chunk allocator.
 *
 * @return A pointer to the new \ref gnn_pbundle of NULL if failed.
 */
gnn_pbundle *
gnn_pbundle_new ()
{
    gnn_pbundle *pb;
    
    /* initialize chunk allocator if not yet */
    if (_ca == NULL)
        _ca = chunkallocator_new (sizeof (gnn_pbundle));

    /* alloc */
    pb = (gnn_pbundle *) chunkallocator_alloc (_ca);
    if (pb == NULL)
        GSL_ERROR_VAL ("could not allocate memory for pbundle",
                                                             GSL_ENOMEM, NULL);
        
    /* set fields */
    pb->c    = 0;
    pb->ph   = NULL;
    pb->next = NULL;
    
    return pb;
}

/**
 * @brief Destroys a \ref gnn_pbundle.
 * @ingroup gnn_pbundle_doc
 *
 * This function destroys a given \ref gnn_pbundle by deallocating its memory
 * and by unreferencing the contained parameter handles.
 *
 * @return A pointer to the new \ref gnn_pbundle of NULL if failed.
 */
void
gnn_pbundle_destroy (gnn_pbundle *pb)
{
    gnn_pbundle *ptr;
    gnn_pbundle *nextptr;
    
    assert (pb != NULL);
    
    ptr = pb;
    while (ptr != NULL)
    {
        gnn_pbundle *nextptr;
        
        nextptr = ptr->next;
        
        if (ptr->ph != NULL)
            gnn_phandle_unref (ptr->ph);
            
        chunkallocator_free (_ca, ptr);
        
        ptr = nextptr;
    }
}

/**
 * @brief Inserts a parameter handle into a parameter bundle.
 * @ingroup gnn_pbundle_doc
 *
 * This function takes a parameter bundle and a parameter handle as arguments.
 * It creates a new \ref gnn_pbundle element associated with the parameter
 * handle and inserts it into the bundle.
 * The argument "n" is the amount of times the given handle should be added.
 *
 * @param  pb A parameter bundle.
 * @param  ph A parameter handle.
 * @param  n  The multiplicity of the handle.
 * @return 0 if succeeded.
 */
int
gnn_pbundle_insert (gnn_pbundle *pb, gnn_phandle *ph, int n)
{
    gnn_pbundle *ptr;

    assert (pb != NULL);
    assert (ph != NULL);
    
    /* search insertion place */
    ptr = pb;
    while ((ptr->next != NULL) && (ptr->next->ph != ph))
        ptr = ptr->next;

    /* insert */
    if (ptr->next == NULL)
    {
        /* alloc */
        ptr->next = (gnn_pbundle *) chunkallocator_alloc (_ca);
        if (ptr->next == NULL)
            GSL_ERROR ("could not alloc memory for pbundle", GSL_ENOMEM);

        ptr = ptr->next;

        /* set fields */
        ptr->c    = n;
        ptr->ph   = ph;
        ptr->next = NULL;
        
        /* increase handle's reference counter */
        gnn_phandle_ref (ptr->ph);
    }
    else
    {
        ptr = ptr->next;
        
        /* increase element multiplicity counter */
        ptr->c += n;
    }

    return 0;
}

/**
 * @brief Removes a parameter handle from a parameter bundle.
 * @ingroup gnn_pbundle_doc
 *
 * This function takes a parameter bundle and a parameter handle as arguments.
 * It removes "n" copies of the given parameter handle from the bundle.
 *
 * @param  pb A parameter bundle.
 * @param  ph A parameter handle.
 * @return 0 if succeeded.
 */
int
gnn_pbundle_remove (gnn_pbundle *pb, const gnn_phandle *ph, int n)
{
    gnn_pbundle *ptr;
    
    assert (pb != NULL);
    assert (ph != NULL);
    
    /* find adecuate position */
    ptr = pb;
    while (pb->next != NULL && pb->next->ph != ph)
        ptr = ptr->next;

    /* remove if found */
    if (pb->next->ph == ph)
    {
        gnn_pbundle *found;
        
        found = ptr->next;

        /* decrease multiplicity counter */
        found->c -= n;
        
        /* remove if counter reached zero */
        if (found->c <= 0)
        {
            ptr->next = ptr->next->next;
            gnn_phandle_unref (found->ph);
            chunkallocator_free (found);
        }
    }
    else
        GSL_ERROR ("parameter handle could not be found in bundle", GSL_EINVAL);
    
    return 0;
}

/**
 * @brief Join two parameter bundles.
 * @ingroup gnn_pbundle_doc
 *
 * This function increases the parameter bundle "pb" with "pbop"'s elements
 * without changing the "pbop" bundle.
 *
 * @param  pb   A parameter bundle.
 * @param  pbop A parameter bundle.
 * @return 0 if suceeded.
 */
int
gnn_pbundle_join (gnn_pbundle *pb, const gnn_pbundle *pbop)
{
    gnn_pbundle *ptr;
    
    assert (pb != NULL);
    assert (pbop != NULL);
    
    /* insert pbop's elements */
    ptr = pbop->next;
    while (ptr != NULL)
    {
        gnn_pbundle_insert (pb, ptr->ph, ptr->c);
        ptr = ptr->next;
    }

    return 0;
}

/**
 * @brief Detach a parameter bundle.
 * @ingroup gnn_pbundle_doc
 *
 * This function removes the parameter bundle "pbop" from "pb", respecting
 * the multiplicity of each element.
 *
 * @param  pb   A parameter bundle.
 * @param  pbop A parameter bundle.
 * @return 0 if suceeded.
 */
int
gnn_pbundle_detach (gnn_pbundle *pb, const gnn_pbundle *pbop)
{
    gnn_pbundle *ptr;
    
    assert (pb != NULL);
    assert (pbop != NULL);
    
    /* remove pbop's elements */
    ptr = pbop->next;
    while (ptr != NULL)
    {
        gnn_pbundle_remove (pb, ptr->ph, ptr->c);
        ptr = ptr->next;
    }

    return 0;
}

/**
 * @brief Get the number of free parameters hold by the bundle.
 * @ingroup gnn_pbundle_doc
 *
 * This function returns the number of free parameters that the bundle manages.
 *
 * @param  pb A paramter bundle.
 * @return The number of free parameters.
 */
int
gnn_pbundle_get_n_free (gnn_pbundle *pb)
{
    int c;
    gnn_pbundle *ptr;

    assert (pb != NULL);

    /* count */
    c   = 0;
    ptr = pb->next;
    while (ptr != NULL)
    {
        c += gnn_phandle_get_free (ptr->ph);
        ptr = ptr->next;
    }

    return c;
}

/**
 * @brief Get the size of the parameter hold by the bundle.
 * @ingroup gnn_pbundle_doc
 *
 * This function returns the number of parameters that the bundle manages.
 *
 * @param  pb A paramter bundle.
 * @return The number of total parameters.
 */
int
gnn_pbundle_get_size (gnn_pbundle *pb)
{
    int c;
    gnn_pbundle *ptr;

    assert (pb != NULL);

    /* count */
    c   = 0;
    ptr = pb->next;
    while (ptr != NULL)
    {
        c += gnn_phandle_get_size (ptr->ph);
        ptr = ptr->next;
    }

    return c;
}



/**
 * @brief Get the complete parameter vector.
 * @ingroup gnn_pbundle_doc
 *
 * This function fills the given real vector with the parameter bundles
 * parameters.
 *
 * @param  pb A parameter bundle.
 * @param  w  A real vector of the correct size.
 * @return 0 if succeeded.
 */
int
gnn_pbundle_get_w (gnn_pbundle *pb, gsl_vector *w)
{
    int poffset;
    gnn_pbundle *ptr;

    assert (pb != NULL);

    /* check null size */
    if (pb->next == NULL)
    {
        if (w != NULL)
            GSL_ERROR ("bundle and vector aren't of the same size", GSL_EINVAL);
        return 0;
    }

    /* copy values */
    poffset = 0;
    ptr     = pb->next;
    while (ptr != NULL)
    {
        size_t size;
        gsl_vector_view w_view;

        size = gnn_phandle_get_size (ptr->ph);
        if (size > 0)
        {
            w_view = gsl_vector_subvector (w, poffset, size);
            gsl_vector_memcpy (&(w_view.vector), gnn_phandle_get_w (ptr->ph));
        }
        
        poffset += size;
        ptr     = ptr->next;
    }

    return 0;
}

/**
 * @brief Set parameter vector.
 * @ingroup gnn_pbundle_doc
 *
 * This function takes fills the parameter bundle with the values given in
 * the real vector w. 
 *
 * @param  pb A pointer to a parameter bundle.
 * @param  w  A pointer to a real vector.
 * @return 0 if succeeded.
 */
int
gnn_pbundle_set_w (gnn_pbundle *pb, const gsl_vector *w)
{
    int poffset;
    gnn_pbundle *ptr;

    assert (pb != NULL);

    /* check null size */
    if (pb->next == NULL)
    {
        if (w != NULL)
            GSL_ERROR ("bundle and vector aren't of the same size", GSL_EINVAL);
        return 0;
    }

    /* copy values */
    poffset = 0;
    ptr     = pb->next;
    while (ptr != NULL)
    {
        size_t size;
        gsl_vector_view w_view;

        size = gnn_phandle_get_size (ptr->ph);
        if (size > 0)
        {
            w_view = gsl_vector_subvector ((gsl_vector *) w, poffset, size);
            gsl_vector_memcpy (gnn_phandle_get_w (ptr->ph), &(w_view.vector));
        }
        
        poffset += size;
        ptr     = ptr->next;
    }

    return 0;
}

/**
 * @brief Set the i-th parameter.
 * @ingroup gnn_pbundle_doc
 *
 * @param  pb A parameter bundle.
 * @param  i  The index of the parameter to be set.
 * @param  wi The new value for the parameter.
 * @return 0 if succeeded.
 */
int
gnn_pbundle_set_w_at (gnn_pbundle *pb, size_t i, double wi)
{
    int poffset;
    gnn_pbundle *ptr;

    assert (pb != NULL);
    assert (i >= 0);

    /* search position */
    poffset = 0;
    ptr     = pb->next;
    while (ptr != NULL && gnn_phandle_get_size (ptr->ph) <= i)
    {
        i  -= gnn_phandle_get_size (ptr->ph);
        ptr = ptr->next;
    }

    /* set value */
    if (ptr == NULL)
        GSL_ERROR ("index out of bounds", GSL_EINVAL);
    gsl_vector_set (gnn_phandle_get_w (ptr->ph), i, wi);

    return 0;
}

/**
 * @brief Sets a value for all parameters.
 * @ingroup gnn_pbundle_doc
 *
 * @param  pb A parameter bundle.
 * @param  wi The new value for the parameter.
 * @return 0 if succeeded.
 */
int
gnn_pbundle_set_w_all (gnn_pbundle *pb, double wi)
{
    gnn_pbundle *ptr;

    assert (pb != NULL);

    /* set all zero */
    ptr = pb->next;
    while (ptr != NULL)
    {
        if (gnn_phandle_get_size (ptr->ph) > 0)
            gsl_vector_set_all (gnn_phandle_get_w (ptr->ph), wi);
        ptr = ptr->next;
    }

    return 0;
}

/**
 * @brief Gets the i-th paramter.
 * @ingroup gnn_pbundle_doc
 *
 * @param  pb A parameter bundle.
 * @param  i  The index of the parameter to be retrieved.
 * @return The value of the i-th parameter.
 */
double
gnn_pbundle_get_w_at (gnn_pbundle *pb, size_t i)
{
    int poffset;
    gnn_pbundle *ptr;

    assert (pb != NULL);
    assert (i >= 0);

    /* search position */
    poffset = 0;
    ptr     = pb->next;
    while (ptr != NULL && gnn_phandle_get_size (ptr->ph) <= i)
    {
        i  -= gnn_phandle_get_size (ptr->ph);
        ptr = ptr->next;
    }

    /* get value */
    if (ptr == NULL)
        GSL_ERROR ("index out of bounds", GSL_EINVAL);

    return gsl_vector_get (gnn_phandle_get_w (ptr->ph), i);
}




/**
 * @brief Gets a the parameter gradient.
 * @ingroup gnn_pbundle_doc
 *
 * This function fills the vector dw with the parameter gradient values of
 * the parameter bundle. The frozen flags are respected.
 *
 * @param  pb A parameter bundle.
 * @param  dw A sufficiently large vector to be filled.
 * @return 0 if succeeded.
 */
int
gnn_pbundle_get_dw (gnn_pbundle *pb, gsl_vector *dw)
{
    int poffset;
    gnn_pbundle *ptr;

    assert (pb != NULL);

    /* check null size */
    if (pb->next == NULL)
    {
        if (dw != NULL)
            GSL_ERROR ("bundle and vector aren't of the same size", GSL_EINVAL);
        return 0;
    }

    /* copy values */
    poffset = 0;
    ptr     = pb->next;
    while (ptr != NULL)
    {
        size_t size;
        gsl_vector_view dw_view;

        size = gnn_phandle_get_size (ptr->ph);
        if (size > 0)
        {
            /* get view */
            dw_view = gsl_vector_subvector (dw, poffset, size);

            /* update handle and copy values */
            gnn_phandle_update (ptr->ph);
            gsl_vector_memcpy (&(dw_view.vector), gnn_phandle_get_dw (ptr->ph));
        }

        poffset += size;
        ptr     = ptr->next;
    }

    return 0;
}

/**
 * @brief Sets a the parameter gradient.
 * @ingroup gnn_pbundle_doc
 *
 * This function fills the parameter bundles paramter gradient vector dw with
 * values given in the argument dw. The values at the frozen positions will be
 * ignored (they are always zero).
 *
 * @param  pb A parameter bundle.
 * @param  dw The values for the parameter gradient.
 * @return 0 if succeeded.
 */
int
gnn_pbundle_set_dw (gnn_pbundle *pb, const gsl_vector *dw)
{
    int poffset;
    gnn_pbundle *ptr;

    assert (pb != NULL);

    /* check null size */
    if (pb->next == NULL)
    {
        if (dw != NULL)
            GSL_ERROR ("bundle and vector aren't of the same size", GSL_EINVAL);
        return 0;
    }

    /* copy values */
    poffset = 0;
    ptr     = pb->next;
    while (ptr != NULL)
    {
        size_t size;
        gsl_vector_view dw_view;

        size = gnn_phandle_get_size (ptr->ph);
        if (size > 0)
        {
            /* get view */
            dw_view = gsl_vector_subvector ((gsl_vector *) dw, poffset, size);

            /* copy values using freeze flags */
            gsl_vector_memcpy (gnn_phandle_get_dw (ptr->ph), &(dw_view.vector));
            gnn_phandle_update (ptr->ph);
        }

        poffset += size;
        ptr     = ptr->next;
    }

    return 0;
}

/**
 * @brief Sets the i-th parameter gradient value.
 * @ingroup gnn_pbundle_doc
 *
 * This function sets the value of the parameter gradient's i-th element.
 * The frozen flags are respected.
 *
 * @param  pb  A parameter bundle.
 * @param  i   The index of the value to be set.
 * @param  dwi The new value for the parameter gradient.
 * @return 0 if succeeded.
 */
int
gnn_pbundle_set_dw_at (gnn_pbundle *pb, size_t i, double dwi)
{
    int poffset;
    gnn_pbundle *ptr;

    assert (pb != NULL);
    assert (i >= 0);

    /* search position */
    poffset = 0;
    ptr     = pb->next;
    while (ptr != NULL && gnn_phandle_get_size (ptr->ph) <= i)
    {
        i  -= gnn_phandle_get_size (ptr->ph);
        ptr = ptr->next;
    }

    /* set value */
    if (ptr == NULL)
        GSL_ERROR ("index out of bounds", GSL_EINVAL);
    if (gsl_vector_int_get (gnn_phandle_get_f (ptr->ph), i) != 0)
        gsl_vector_set (gnn_phandle_get_dw (ptr->ph), i, dwi);

    return 0;
}

/**
 * @brief Sets a unique value for all the parameter gradient's elements.
 * @ingroup gnn_pbundle_doc
 *
 * This function fills the vector dw with the value given as dwi. The
 * frozen flags are respected.
 *
 * @param  pb  A parameter bundle.
 * @param  dwi The new value for the parameter.
 * @return 0 if succeeded.
 */
int
gnn_pbundle_set_dw_all (gnn_pbundle *pb, double dwi)
{
    gnn_pbundle *ptr;

    assert (pb != NULL);

    /* set all */
    ptr = pb->next;
    while (ptr != NULL)
    {
        if (gnn_phandle_get_size (ptr->ph) > 0)
        {
            gsl_vector_set_all (gnn_phandle_get_dw (ptr->ph), dwi);
            gnn_phandle_update (ptr->ph);
        }
        
        ptr = ptr->next;
    }

    return 0;
}

/**
 * @brief Gets the i-th parameter gradient.
 * @ingroup gnn_pbundle_doc
 *
 * This function returns the i-th parameter gradient, respecting its frozen
 * flag.
 *
 * @param  pb A parameter bundle.
 * @param  i  Index of the parameter gradient to be retrieved.
 * @return The i-th parameter gradient.
 */
double
gnn_pbundle_get_dw_at (gnn_pbundle *pb, size_t i)
{
    int poffset;
    gnn_pbundle *ptr;

    assert (pb != NULL);
    assert (i >= 0);

    /* search position */
    poffset = 0;
    ptr     = pb->next;
    while (ptr != NULL && gnn_phandle_get_size (ptr->ph) <= i)
    {
        i  -= gnn_phandle_get_size (ptr->ph);
        ptr = ptr->next;
    }

    /* set value */
    if (ptr == NULL)
        GSL_ERROR ("index out of bounds", GSL_EINVAL);

    if (gsl_vector_int_get (gnn_phandle_get_f (ptr->ph), i) != 0)
        return gsl_vector_get (gnn_phandle_get_dw (ptr->ph), i);
    else
        return 0.0;
}



/**
 * @brief Gets freeze flag vector.
 * @ingroup gnn_pbundle_doc
 *
 * @param  pb A parameter bundle.
 * @param  f  A buffer vector to be filled with the freeze flags of the
 *            correct size.
 * @return 0 if succeeded.
 */
int
gnn_pbundle_get_f (gnn_pbundle *pb, gsl_vector_int *f)
{
    int poffset;
    gnn_pbundle *ptr;

    assert (pb != NULL);

    /* check null size */
    if (pb->next == NULL)
    {
        if (f != NULL)
            GSL_ERROR ("bundle and vector aren't of the same size", GSL_EINVAL);
        return 0;
    }

    /* copy values */
    poffset = 0;
    ptr     = pb->next;
    while (ptr != NULL)
    {
        size_t size;
        gsl_vector_int_view f_view;

        size = gnn_phandle_get_size (ptr->ph);
        if (size > 0)
        {
            f_view = gsl_vector_int_subvector ((gsl_vector_int *) f,
                                                                 poffset, size);
            gsl_vector_int_memcpy (&(f_view.vector),
                                   gnn_phandle_get_f (ptr->ph));
        }
        
        poffset += gnn_phandle_get_size (ptr->ph);
        ptr     = ptr->next;
    }

    return 0;
}

/**
 * @brief Sets the freeze flags.
 * @ingroup gnn_pbundle_doc
 *
 * This function fills freeze flags vector with the binary {0,1} values given
 * in the integer vector f.
 *
 * @param  pb A parameter bundle.
 * @param  f  A integer vector with binary values.
 * @return 0 if succeeded.
 */
int
gnn_pbundle_set_f (gnn_pbundle *pb, const gsl_vector_int *f)
{
    int poffset;
    gnn_pbundle *ptr;

    assert (pb != NULL);

    /* check null size */
    if (pb->next == NULL)
    {
        if (f != NULL)
            GSL_ERROR ("bundle and vector aren't of the same size", GSL_EINVAL);
        return 0;
    }

    /* copy values */
    poffset = 0;
    ptr     = pb->next;
    while (ptr != NULL)
    {
        size_t size;
        gsl_vector_int_view f_view;

        size = gnn_phandle_get_size (ptr->ph);
        if (size > 0)
        {
            /* set local values */
            f_view = gsl_vector_int_subvector ((gsl_vector_int *) f,
                                                        poffset, size);
            gsl_vector_int_memcpy (gnn_phandle_get_f (ptr->ph),
                                                      &(f_view.vector));
        
            /* update phandle */
            gnn_phandle_update (ptr->ph);
        }
        
        poffset += size;
        ptr     = ptr->next;
    }

    return 0;
}

/**
 * @brief Sets the i-th freeze flag.
 * @ingroup gnn_pbundle_doc
 *
 * @param  pb A parameter bundle.
 * @param  i  The index of the freeze flag to be set.
 * @param  fi The value (0=free or 1=frozen) of the flag.
 * @return 0 if succeeded.
 */
int
gnn_pbundle_set_f_at (gnn_pbundle *pb, size_t i, int fi)
{
    int poffset;
    gnn_pbundle *ptr;

    assert (pb != NULL);
    assert (i >= 0);
    assert (fi == 0 || fi == 1);

    /* search position */
    poffset = 0;
    ptr     = pb->next;
    while (ptr != NULL && gnn_phandle_get_size (ptr->ph) <= i)
    {
        i  -= gnn_phandle_get_size (ptr->ph);
        ptr = ptr->next;
    }

    /* set value */
    if (ptr == NULL)
        GSL_ERROR ("index out of bounds", GSL_EINVAL);
    gsl_vector_int_set (gnn_phandle_get_f (ptr->ph), i, fi);
    
    /* update handle */
    gnn_phandle_update (ptr->ph);

    return 0;
}

/**
 * @brief Sets a value for all freeze flags.
 * @ingroup gnn_pbundle_doc
 *
 * This function fills the freeze flag vector with the value given a parameter.
 *
 * @param  pb A parameter bundle.
 * @param  fi The new value for all freeze flags. It should be 0 (free) or
 *            1 (frozen).
 * @return 0 if succeeded.
 */
int
gnn_pbundle_set_f_all (gnn_pbundle *pb, int fi)
{
    gnn_pbundle *ptr;

    assert (pb != NULL);
    assert (fi == 0 || fi == 1);

    /* set all */
    ptr = pb->next;
    while (ptr != NULL)
    {
        if (gnn_phandle_get_size (ptr->ph) > 0)
        {
            gsl_vector_int_set_all (gnn_phandle_get_f (ptr->ph), fi);
            gnn_phandle_update (ptr->ph);
        }
        
        ptr = ptr->next;
    }

    return 0;
}

/**
 * @brief Gets the i-th freeze flag.
 * @ingroup gnn_pbundle_doc
 *
 * @param  pb A parameter bundle.
 * @param  i  The indexof the freeze flag to be returned.
 * @return 0 if the i-th parameter is free or 1 if frozen.
 */
int
gnn_pbundle_get_f_at (gnn_pbundle *pb, size_t i)
{
    int poffset;
    gnn_pbundle *ptr;

    assert (pb != NULL);
    assert (i >= 0);

    /* search position */
    poffset = 0;
    ptr     = pb->next;
    while (ptr != NULL && gnn_phandle_get_size (ptr->ph) <= i)
    {
        i  -= gnn_phandle_get_size (ptr->ph);
        ptr = ptr->next;
    }

    /* set value */
    if (ptr == NULL)
        GSL_ERROR ("index out of bounds", GSL_EINVAL);

    return gsl_vector_int_get (gnn_phandle_get_f (ptr->ph), i);
}

---