---

gnn_weight.c

Go to the documentation of this file.

/***************************************************************************
 *  @file  gnn_weight.c
 *  @brief gnn_weight Implementation.
 *
 *  @date   : 15-07-03 19:56
 *  @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_weight_doc gnn_weight : Affine / Linear Transform
 * @ingroup gnn_atomic_doc
 * @todo Include more transformations (1-D and 2-D), and check other uses.
 *
 * The \ref gnn_weight node type implements the function given by
 * \f[ Y = A X + B \f]
 * where \f$A\f$ is a matrix of size \f$m \times n\f$ and \f$B\f$
 * is a vector of size \f$m \times 1\f$. Basically, the \ref gnn_weight
 * computes an affine transform. Using the nomenclature used in relation with
 * neural networks, the matrix \f$A\f$ is the "weights matrix" and \f$B\f$
 * is the "bias vector".
 *
 * The same function written in index notation is:
 * \f[ y_j = \sum_i A_{ji} x_i + B_{j} \f]
 * where the index \f$j\f$ runs over all outputs, i.e. \f$j=1,\ldots,m\f$
 * and \f$i\f$ runs over the inputs \f$i=1,\ldots,n\f$. The following figure
 * shows how the different terms affect the inputs:
 *
 * <img src="images/gnn_weight1.png">
 *
 * The \ref gnn_weight node is very versatile. Depending on the point of
 * view, it can be seen as carrying out many different types of functions.
 *
 * A new weight layer can be built using the \ref gnn_weight_new function.
 * There are several ways to initialize or set its values. These can be
 * set per example set randomly with \ref gnn_weight_init, or fixed with
 * alternative linear transforms like Cosine Transform, Hadamard or
 * Karhunen-Loeve. The matrix \f$A\f$ can be though as a graph's adyacency
 * matrix, where \f$A_{ji}\f$ corresponds to the connection strength of
 * the input \f$x_i\f$ with the output \f$y_j\f$. 
 */

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

#include <math.h>
#include <gsl/gsl_blas.h>
#include <gsl/gsl_randist.h>
#include <gsl/gsl_eigen.h>
#include "gnn_utilities.h"
#include "gnn_weight.h"



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

/**
 * @brief The structure for a \ref gnn_weight node.
 * @ingroup gnn_weight_doc
 *
 * This datatype holds the information for a \ref gnn_weight node. Basically,
 * it extends the \ref gnn_node with special pointers to get fast accesses
 * to the matrices and vectors \f$A\f$, \f$B\f$,
 * \f$\frac{\partial E}{\partial A}\f$, \f$\frac{\partial E}{\partial B}\f$
 * and their frozen flags in order to improve the efficiency.
 */
typedef struct _gnn_weight gnn_weight;

struct _gnn_weight
{
    gnn_node node;               /**< The underlying \ref gnn_node. */

    int linear;                  /**< No use yet. */

    gsl_matrix_view      A_view; /**< View of matrix A.             */
    gsl_vector_view      B_view; /**< View of vector B.             */
    gsl_matrix_view     dA_view; /**< View of matrix dA.            */
    gsl_vector_view     dB_view; /**< View of vector dB.            */
    gsl_matrix_int_view Af_view; /**< View of flags for A.          */
    gsl_vector_int_view Bf_view; /**< View of flags for B.          */

    gsl_matrix     *A;           /**< Pointer to matrix A.          */
    gsl_vector     *B;           /**< Pointer to vector B.          */
    gsl_matrix     *dA;          /**< Pointer to matrix dA.         */
    gsl_vector     *dB;          /**< Pointer to vector dB.         */
    gsl_matrix_int *Af;          /**< Pointer to flags for A.       */
    gsl_vector_int *Bf;          /**< Pointer to flags for B.       */

};


static int
gnn_weight_f (gnn_node *node,
              const gsl_vector *x,
              const gsl_vector *w,
              gsl_vector *y);


static int
gnn_weight_dx (gnn_node *node,
               const gsl_vector *x,
               const gsl_vector *w,
               const gsl_vector *dy,
               gsl_vector *dx);

static int
gnn_weight_dw (gnn_node *node,
               const gsl_vector *x,
               const gsl_vector *w,
               const gsl_vector *dy,
               gsl_vector *dw);


static void
gnn_weight_destroy (gnn_node *node);



static int
gnn_weight_hadamard_recurse (gsl_matrix *A, double fact);



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

/**
 * @brief Computes the evaluation.
 * @ingroup gnn_weight_doc
 *
 * This functions computes:
 * \f[ y_j = \sum_{i=1}^n A_{ji} x_i + B_i \f]
 * or written in matrix notation:
 * \f[ Y = A x + B \f]
 *
 * @param node A pointer to a \ref gnn_weight node.
 * @param x    A pointer to the input vector \f$x\f$.
 * @param w    A pointer to the parameter vector \f$w\f$.
 * @param y    A pointer to the output vector \f$y\f$ where the result should
 *             be placed.
 * @return Returns 0 if suceeded.
 */
static int
gnn_weight_f (gnn_node *node,
              const gsl_vector *x,
              const gsl_vector *w,
              gsl_vector *y)
{
    gnn_weight *wnode;

    wnode = (gnn_weight *) node;

    /* compute output */
    gsl_vector_add (y, wnode->B);
    gsl_blas_dgemv (CblasNoTrans, 1.0, wnode->A, x, 0.0, y);

    return 0;
}

/**
 * @brief Computes the \ref gnn_weight gradient with respect to its inputs.
 * @ingroup gnn_weight_doc
 *
 * This functions computes:
 * \f[\frac{\partial E}{\partial x_j} =
 *     \sum_j A_{ji} \frac{\partial E}{\partial y_j}\f]
 * or, written in matrix notation:
 * \f[ \frac{\partial E}{\partial x} =
 *     A^t \frac{\partial E}{\partial y} \f]
 *
 * @param node A pointer to a \ref gnn_weight node.
 * @param x    A pointer to the input vector \f$x\f$.
 * @param w    A pointer to the parameter vector \f$w\f$.
 * @param dy   A pointer to the vector \f$\frac{\partial E}{\partial y}\f$.
 * @param dx   A pointer to the vector \f$\frac{\partial E}{\partial x}\f$
 *             where the result should be placed.
 * @return Returns 0 if suceeded.
 */
static int
gnn_weight_dx (gnn_node *node,
               const gsl_vector *x,
               const gsl_vector *w,
               const gsl_vector *dy,
               gsl_vector *dx)
{
    gnn_weight *wnode;

    wnode = (gnn_weight *) node;

    /* compute output */
    gsl_blas_dgemv (CblasTrans, 1.0, wnode->A, dy, 0.0, dx);

    return 0;
}


/**
 * @brief Computes the \ref gnn_weight gradient with respect to its parameters.
 * @ingroup gnn_weight_doc
 *
 * This functions computes:
 * \f[ \frac{\partial E}{\partial A_{ji}} =
 *     x_i \frac{\partial E}{\partial y_j} \f]
 * \f[ \frac{\partial E}{\partial B_i} =
 *     \frac{\partial E}{\partial y_j} \f]
 * where \f$x_0\f$ is defined as \f$1\f$. Or written in matrix notation:
 * \f[ \frac{\partial E}{\partial A} =
 *     \frac{\partial E}{\partial y}^t x \f]
 * and
 * \f[ \frac{\partial E}{\partial B} =
 *     \frac{\partial E}{\partial y}^t \f]
 *
 * @param node A pointer to a \ref gnn_weight node.
 * @param x    A pointer to the input vector \f$x\f$.
 * @param w    A pointer to the parameter vector \f$w\f$.
 * @param dy   A pointer to the vector \f$\frac{\partial E}{\partial y}\f$.
 * @param dw   A pointer to the vector \f$\frac{\partial E}{\partial w}\f$
 *             where the result should be placed.
 * @return Returns 0 if suceeded.
 */
static int
gnn_weight_dw (gnn_node *node,
               const gsl_vector *x,
               const gsl_vector *w,
               const gsl_vector *dy,
               gsl_vector *dw)
{
    int input_size;
    int output_size;
    gsl_matrix_view X;
    gsl_matrix_view DY;
    gnn_weight *wnode;

    wnode = (gnn_weight *) node;

    /* get sizes */
    input_size  = gnn_node_input_get_size (node);
    output_size = gnn_node_output_get_size (node);

    /* get matrix and vector view */
    X  = gsl_matrix_view_vector ((gsl_vector *) x, 1, input_size);
    DY = gsl_matrix_view_vector ((gsl_vector *) dy, output_size, 1);

    /* compute output */
    gsl_blas_dgemm (CblasNoTrans, CblasNoTrans, 1.0, &(DY.matrix),
                                                &(X.matrix), 1.0, wnode->dA);
    gsl_vector_add (wnode->dB, dy);

    return 0;
}

/**
 * @brief The destroy function for a \ref gnn_weight.
 * @ingroup gnn_weight_doc
 *
 * This functions computes is the \ref gnn_weight destroy function, which
 * destroys the type's specific data.
 *
 * @param node A pointer to a \ref gnn_weight.
 */
static void
gnn_weight_destroy (gnn_node *node)
{
    return;
}


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

/**
 * @brief Creates a new \ref gnn_weight layer.
 * @ingroup gnn_weight_doc
 *
 * This function creates a new \ref gnn_node of \ref gnn_weight type.
 *
 * @param input_size The node's input size.
 * @param output_size The node's output size.
 * @return A new node.
 */
gnn_node *
gnn_weight_new (int input_size, int output_size)
{
    int status;
    int param_size;
    gnn_node   *node;
    gnn_weight *wnode;
    gsl_vector *w;
    gsl_vector *dw;
    gsl_vector_int *f;
    
    /* check if sizes are positive */
    if (input_size < 1 || output_size < 1)
    {
        GSL_ERROR_VAL ("gnn_weight's sizes should be stricly positive",
                       GSL_EINVAL, NULL);
    }
    
    /* compute amount of needed parameters */
    param_size = input_size * output_size + output_size;

    /* allocate the node */
    node = (gnn_node *) malloc (sizeof (gnn_weight));
    if (node == NULL)
        GSL_ERROR_VAL ("couldn't allocate memory for gnn_weight's node",
                       GSL_ENOMEM, NULL);

    /* Initialize the node */
    status = gnn_node_init (node,
                            "gnn_weight",
                            gnn_weight_f,
                            gnn_weight_dx,
                            gnn_weight_dw,
                            gnn_weight_destroy);
    if (status)
        GSL_ERROR_VAL ("could not initialize weights node", GSL_EINVAL, NULL);
        
    status = gnn_node_set_sizes (node, input_size, output_size, param_size);
    if (status)
        GSL_ERROR_VAL ("could not set sizes for weights node", GSL_EINVAL, NULL);

    /* get references for building views */
    wnode = (gnn_weight *) node;
    w     = gnn_node_local_get_w (node);
    dw    = gnn_node_local_get_dw (node);
    f     = gnn_node_local_get_f (node);

    /* build views */
    wnode->A_view  = gsl_matrix_view_vector (w, output_size, input_size);
    wnode->B_view  = gsl_vector_subvector (w, input_size * output_size,
                                                 output_size);
                                                 
    wnode->dA_view = gsl_matrix_view_vector (dw, output_size, input_size);
    wnode->dB_view = gsl_vector_subvector (dw, input_size * output_size,
                                                  output_size);

    wnode->Af_view = gsl_matrix_int_view_vector (f, output_size, input_size);
    wnode->Bf_view = gsl_vector_int_subvector (f, input_size * output_size,
                                                     output_size);

    /* build pointers */
    wnode->A = &(wnode->A_view.matrix);
    wnode->B = &(wnode->B_view.vector);
    wnode->dA = &(wnode->dA_view.matrix);
    wnode->dB = &(wnode->dB_view.vector);
    wnode->Af = &(wnode->Af_view.matrix);
    wnode->Bf = &(wnode->Bf_view.vector);
        
    return node;
}

/**
 * @brief Initializes the layer's parameters.
 * @ingroup gnn_weight_doc
 *
 * This functions initializes the layer's parameters by values drawn from
 * a uniform distribution with mean zero and standard deviation
 * \f[ \sigma = (n + 1)^{-\frac{1}{2}}  \f]
 * to insure that each of the outputs \f$y_j\f$ are approximately \f$1\f$.
 *
 * Implementation Note: The numbers are generated by
 * \f[ \frac {1}{ \sqrt {12} \sigma } (x - \frac{1}{2}) \f]
 * where \f$x\f$ is drawn from a uniform distribution in \f$[0, 1)\f$.
 *
 * @param layer A pointer to a \ref gnn_weight node.
 * @return Returns 0 on success.
 */
int
gnn_weight_init (gnn_node *node)
{
    int    i;
    int    l;
    double sigma;
    double sqrt12;
    double amplitude;
    gsl_rng    *r;
    gsl_vector *w;

    /* get the random number generator */
    r = gnn_get_rng ();

    /* get the parameters */
    w = gnn_node_local_get_w (node);
    l = w->size;

    /* compute the amplitude of the uniform distribution */
    sigma      = 1.0 / sqrt (l);
    sqrt12     = sqrt (12.0);
    amplitude  = 1.0 / (sqrt12 * sigma);

    /* initialize weights */
    for (i=0; i<l; ++i)
    {
        double random_value;
        random_value = amplitude * (gsl_rng_uniform (r) - 0.5);
        gsl_vector_set (w, i, random_value);
    }

    /* update change */
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Gets the node's parameter matrix \f$A\f$.
 * @ingroup gnn_weight_doc
 *
 * This function a pointer to the node's internal parameter matrix \f$A\f$.
 * Its values can be freely modified, but after changes are made, the
 * \ref gnn_node_local_update function should be called.
 *
 * @param node A pointer to a \ref gnn_weight.
 * @return A pointer to a matrix.
 */
gsl_matrix *
gnn_weight_get_A (gnn_node *node)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_w (node);
    wnode = (gnn_weight *) node;
    return wnode->A;
}

/**
 * @brief Gets the node's parameter vector \f$B\f$.
 * @ingroup gnn_weight_doc
 *
 * This function a pointer to the node's internal parameter vector \f$B\f$.
 * Its values can be freely modified, but after changes are made, the
 * \ref gnn_node_local_update function should be called.
 *
 * @param node A pointer to a \ref gnn_node.
 * @return A pointer to a vector.
 */
gsl_vector *
gnn_weight_get_B (gnn_node *node)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_w (node);
    wnode = (gnn_weight *) node;
    return wnode->B;
}

/**
 * @brief Gets \f$\frac{\partial E}{\partial A}\f$.
 * @ingroup gnn_weight_doc
 *
 * This function a pointer to the node's internal parameter matrix
 * gradient \f$\frac{\partial E}{\partial A}\f$.
 * Its values can be freely modified, but after changes are made, the
 * \ref gnn_node_local_update function should be called.
 *
 * @param node A pointer to a \ref gnn_weight.
 * @return A pointer to a matrix.
 */
gsl_matrix *
gnn_weight_get_dA (gnn_node *node)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_dw (node);
    wnode = (gnn_weight *) node;
    return wnode->dA;
}

/**
 * @brief Gets \f$\frac{\partial E}{\partial B}\f$.
 * @ingroup gnn_weight_doc
 *
 * This function a pointer to the node's internal parameter vector gradient
 * \f$\frac{\partial E}{\partial B}\f$.
 * Its values can be freely modified, but after changes are made, the
 * \ref gnn_node_local_update function should be called.
 *
 * @param node A pointer to a \ref gnn_node.
 * @return A pointer to a vector.
 */
gsl_vector *
gnn_weight_get_dB (gnn_node *node)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_dw (node);
    wnode = (gnn_weight *) node;
    return wnode->dB;
}

/**
 * @brief Gets the frozen flags for the matrix \f$A\f$.
 * @ingroup gnn_weight_doc
 *
 * This function returns a pointer to the node's internal matrix frozen flags.
 * Its values can be freely modified, but after changes are made, the
 * \ref gnn_node_local_update function should be called. Remember that
 * these values should be binary, beeing either 0 (free) or 1 (frozen).
 *
 * @param node A pointer to a \ref gnn_weight.
 * @return A pointer to a matrix.
 */
gsl_matrix_int *
gnn_weight_get_Af (gnn_node *node)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;
    return wnode->Af;
}

/**
 * @brief Gets the frozen flags for the vector \f$B\f$.
 * @ingroup gnn_weight_doc
 *
 * This function returns a pointer to the node's internal vector frozen flags.
 * Its values can be freely modified, but after changes are made, the
 * \ref gnn_node_local_update function should be called. Remember that
 * these values should be binary, beeing either 0 (free) or 1 (frozen).
 *
 * @param node A pointer to a \ref gnn_node.
 * @return A pointer to a vector.
 */
gsl_vector_int *
gnn_weight_get_Bf (gnn_node *node)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;
    return wnode->Bf;
}



/**
 * @brief Connectionist Tools for gnn_weight.
 * @defgroup gnn_weight_conn gnn_weight Connectionist Tools.
 * @ingroup gnn_weight_doc
 *
 * This set of functions provide the needed funcionality for manipulating a
 * \ref gnn_weight node from a Connectionist's point of view. That is, the
 * \ref gnn_weight node is viewed as device that maps the inputs to outputs
 * via connections of different strength.
 *
 * The functions in this section allow to establish individual connections
 * from a source \f$x_i\f$ to a destiny \f$y_j\f$. The biases are special
 * connections whose sources are constant and equal to 1.
 */



/**
 * @brief Connect an input with an output.
 * @ingroup gnn_weight_conn
 *
 * Connects the i-th input to the j-th output with the given strength and
 * unfreezes it.
 *
 * @param  node A \ref gnn_weight node.
 * @param  i    The index of the input.
 * @param  j    The index of the output.
 * @param  strength The strength of the connection.
 * @return Returns 0 if suceeded.
 */
int
gnn_weight_connect (gnn_node *node, size_t i, size_t j, double strength)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_w (node);
    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;

    /* set the strength and open parameter */
    gsl_matrix_set (wnode->A, j, i, strength);
    gsl_matrix_int_set (wnode->Af, j, i, 0);
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Disconnect an input with an output.
 * @ingroup gnn_weight_conn
 *
 * Disconnects the i-th input to the j-th output. The weight will be frozen
 * to 0.
 *
 * @param  node A \ref gnn_weight node.
 * @param  i    The index of the input.
 * @param  j    The index of the output.
 * @return Returns 0 if suceeded.
 */
int
gnn_weight_disconnect (gnn_node *node, size_t i, size_t j)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_w (node);
    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;

    /* set the strength and freeze parameter */
    gsl_matrix_set (wnode->A, j, i, 0.0);
    gsl_matrix_int_set (wnode->Af, j, i, 1);
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Creates a full connection.
 * @ingroup gnn_weight_conn
 *
 * Connects the all input to the outputs with the given strength. The
 * connections will be unfrozen.
 *
 * @param  node A \ref gnn_weight node.
 * @param  strength The strength of the connection.
 * @return Returns 0 if suceeded.
 */
int
gnn_weight_connect_all (gnn_node *node, double strength)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_w (node);
    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;

    /* set the strength and open parameter */
    gsl_matrix_set_all (wnode->A, strength);
    gsl_matrix_int_set_all (wnode->Af, 0);
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Disconnect all connections.
 * @ingroup gnn_weight_conn
 *
 * Disconnects all connections. The weights will be frozen to 0.
 *
 * @param  node A \ref gnn_weight node.
 * @return Returns 0 if suceeded.
 */
int
gnn_weight_disconnect_all (gnn_node *node)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_w (node);
    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;

    /* set the strength and freeze parameter */
    gsl_matrix_set_zero (wnode->A);
    gsl_matrix_int_set_all (wnode->Af, 1);
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Connects the i-th input to all outputs with given strength.
 * @ingroup gnn_weight_conn
 *
 * Connects the input at index \a i to all outputs with the given strengh
 * \a strength. The connections will be unfrozen.
 *
 * @param  node A \ref gnn_weight node.
 * @param  i    The input's index.
 * @param  strength The strength of the connections.
 * @return Returns 0 if suceeded.
 */
int
gnn_weight_connect_input (gnn_node *node, size_t i, double strength)
{
    gnn_weight *wnode;
    gsl_vector_view Acol;
    gsl_vector_int_view Afcol;

    assert (node != NULL);

    /* check that the input index is within bounds */
    if (i < 0 || wnode->A->size2 <= i)
    {
        GSL_ERROR ("the input's index is out of bounds", GSL_EINVAL);
    }

    gnn_node_local_get_w (node);
    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;

    /* build the views for the i-th column */
    Acol  = gsl_matrix_column (wnode->A, i);
    Afcol = gsl_matrix_int_column (wnode->Af, i);

    /* set the strength and open parameter */
    gsl_vector_set_all (&(Acol.vector), strength);
    gsl_vector_int_set_all (&(Afcol.vector), 0);
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Disconnect the i-th input from all outputs.
 * @ingroup gnn_weight_conn
 *
 * Disconnects the i-th input from all outputs. The weights will be frozen to 0.
 *
 * @param  node A \ref gnn_weight node.
 * @param  i    The input's index.
 * @return Returns 0 if suceeded.
 */
int
gnn_weight_disconnect_input (gnn_node *node, size_t i)
{
    gnn_weight *wnode;
    gsl_vector_view Acol;
    gsl_vector_int_view Afcol;

    assert (node != NULL);

    /* check that the input index is within bounds */
    if (i < 0 || wnode->A->size2 <= i)
    {
        GSL_ERROR ("the input's index is out of bounds", GSL_EINVAL);
    }

    gnn_node_local_get_w (node);
    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;

    /* build the views for the i-th column */
    Acol  = gsl_matrix_column (wnode->A, i);
    Afcol = gsl_matrix_int_column (wnode->Af, i);

    /* set the strength and freeze parameter */
    gsl_vector_set_zero (&(Acol.vector));
    gsl_vector_int_set_all (&(Afcol.vector), 1);
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Freeze a connection.
 * @ingroup gnn_weight_conn
 *
 * Freezes the connection from the i-th input to he j-th output.
 *
 * @param  node A \ref gnn_weight node.
 * @param  i    The index of the input.
 * @param  j    The index of the output.
 * @return Returns 0 if suceeded.
 */
int
gnn_weight_freeze_connection (gnn_node *node, size_t i, size_t j)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;

    /* parameter */
    gsl_matrix_int_set (wnode->Af, j, i, 1);
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Unfreeze a connection.
 * @ingroup gnn_weight_conn
 *
 * Unfreezes the connection going from the i-th input to the j-th output.
 *
 * @param  node A \ref gnn_weight node.
 * @param  i    The index of the input.
 * @param  j    The index of the output.
 * @return Returns 0 if suceeded.
 */
int
gnn_weight_unfreeze_connection (gnn_node *node, size_t i, size_t j)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;

    /* parameter */
    gsl_matrix_int_set (wnode->Af, j, i, 0);
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Freeze all connections.
 * @ingroup gnn_weight_conn
 *
 * Freezes all the connections.
 *
 * @param  node A \ref gnn_weight node.
 * @return Returns 0 if suceeded.
 */
int
gnn_weight_freeze_all_connections (gnn_node *node)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;

    /* parameter */
    gsl_matrix_int_set_all (wnode->Af, 1);
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Unfreeze all connections.
 * @ingroup gnn_weight_conn
 *
 * Unfreezes all the connections.
 *
 * @param  node A \ref gnn_weight node.
 * @return Returns 0 if suceeded.
 */
int
gnn_weight_unfreeze_all_connections (gnn_node *node)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;

    /* parameter */
    gsl_matrix_int_set_all (wnode->Af, 0);
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Connects a bias.
 * @ingroup gnn_weight_conn
 *
 * Connects the bias associated with the j-th output with the given strength.
 * The value will be unfrozen.
 *
 * @param  node     A \ref gnn_weight node.
 * @param  j        The index of the output associated to the bias.
 * @param  strength The strength of the connection.
 * @return Returns 0 if suceeded.
 */
int
gnn_weight_connect_bias (gnn_node *node, size_t j, double strength)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_w (node);
    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;

    /* set the strength and open parameter */
    gsl_vector_set (wnode->B, j, strength);
    gsl_vector_int_set (wnode->Bf, j, 0);
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Disconnects a bias.
 * @ingroup gnn_weight_conn
 *
 * Disconnects the bias associated with the j-th output.
 * The value will be frozen to 0.
 *
 * @param  node     A \ref gnn_weight node.
 * @param  j        The index of the output associated to the bias.
 * @return Returns 0 if suceeded.
 */
int
gnn_weight_disconnect_bias (gnn_node *node, size_t j)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_w (node);
    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;

    /* set the strength and freeze parameter */
    gsl_vector_set (wnode->B, j, 0.0);
    gsl_vector_int_set (wnode->Bf, j, 1);
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Connects all biases.
 * @ingroup gnn_weight_conn
 *
 * Connects all biases with the given strength.
 * All its values will be unfrozen.
 *
 * @param  node     A \ref gnn_weight node.
 * @param  strength The strength of the connection.
 * @return Returns 0 if suceeded.
 */
int
gnn_weight_connect_all_bias (gnn_node *node, double strength)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_w (node);
    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;

    /* set the strength and open parameter */
    gsl_vector_set_all (wnode->B, strength);
    gsl_vector_int_set_zero (wnode->Bf);
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Disconnects all biases.
 * @ingroup gnn_weight_conn
 *
 * Disconnects all biases. All its values will be frozen to 0.
 *
 * @param  node     A \ref gnn_weight node.
 * @return Returns 0 if suceeded.
 */
int
gnn_weight_disconnect_all_bias (gnn_node *node)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_w (node);
    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;

    /* set the strength and freeze parameter */
    gsl_vector_set_all (wnode->B, 0.0);
    gsl_vector_int_set_all (wnode->Bf, 1);
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Freeze a bias.
 * @ingroup gnn_weight_conn
 *
 * Freezes the bias associated to the j-th output.
 *
 * @param  node A \ref gnn_weight node.
 * @param  j    The index of the output.
 * @return Returns 0 if suceeded.
 */
int
gnn_weight_freeze_bias (gnn_node *node, size_t j)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;

    /* parameter */
    gsl_vector_int_set (wnode->Bf, j, 1);
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Unfreeze a bias.
 * @ingroup gnn_weight_conn
 *
 * Unfreezes the bias associated to the j-th output.
 *
 * @param  node A \ref gnn_weight node.
 * @param  j    The index of the output.
 * @return Returns 0 if suceeded.
 */
int
gnn_weight_unfreeze_bias (gnn_node *node, size_t j)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;

    /* parameter */
    gsl_vector_int_set (wnode->Bf, j, 0);
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Freeze all biases.
 * @ingroup gnn_weight_conn
 *
 * Freezes all biases.
 *
 * @param  node A \ref gnn_weight node.
 * @return Returns 0 if suceeded.
 */
int
gnn_weight_freeze_all_biases (gnn_node *node)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;

    /* parameter */
    gsl_vector_int_set_all (wnode->Bf, 1);
    gnn_node_local_update (node);

    return 0;
}

/**
 * @brief Unfreeze all biases.
 * @ingroup gnn_weight_conn
 *
 * Unfreezes all biases.
 *
 * @param  node A \ref gnn_weight node.
 * @return Returns 0 if suceeded.
 */
int
gnn_weight_unfreeze_all_biases (gnn_node *node)
{
    gnn_weight *wnode;

    assert (node != NULL);

    gnn_node_local_get_f (node);
    wnode = (gnn_weight *) node;

    /* parameter */
    gsl_vector_int_set_all (wnode->Bf, 0);
    gnn_node_local_update (node);

    return 0;
}

---