---

gnn_node.h

Go to the documentation of this file.

/***************************************************************************
 *  @file  gnn_node.h
 *  @brief gnn_node Header File.
 *
 *  @date   : 11-08-03 22:45
 *  @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.
 */

#ifndef _GNN_NODE_H_
#define _GNN_NODE_H_

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

#include "gnn_pbundle.h"



/******************************************/
/* Macros                                 */
/******************************************/

#define GNN_NODE_SUB_INSTALL(_node_, _size_, _status_)            \
{                                                                 \
    va_list args;                                                 \
    va_start(args, (_size_));                                     \
    (_status_) = gnn_node_sub_install ((_node_), (_size_), args); \
    va_end(args);                                                 \
}



/******************************************/
/* Typedefs                               */
/******************************************/

/**
 * @brief   gnn_node type definition.
 * @ingroup gnn_node_ext
 *
 * The gnn_node C type for \ref libgnn node implementations.
 */
typedef struct _gnn_node gnn_node;

/**
 * @brief gnn_node_f type definition.
 * @ingroup gnn_node_ext
 *
 * This is the type for gnn_node's evaluation functions.
 * An example function is:
 * \code
 * int my_func (gnn_node *node,
 *              const gsl_vector *x,
 *              const gsl_vector *w,
 *              gsl_vector *y)
 * {
 *     // function implementation
 *     ...
 * }
 * \endcode
 */
typedef int
        (*gnn_node_f) (gnn_node         *node,
                       const gsl_vector *x,
                       const gsl_vector *w,
                       gsl_vector *y);

/**
 * @brief gnn_node_df type definition.
 * @ingroup gnn_node_ext
 *
 * This is the type for gnn_node's evaluation function gradients.
 * An example function is:
 * \code
 * int my_func_gradient (gnn_node *node,
 *                       const gsl_vector *x,
 *                       const gsl_vector *w,
 *                       const gsl_vector *dy,
 *                       gsl_vector       *dw);
 * {
 *     // function implementation
 *     ...
 * }
 * \endcode
 */
typedef int
        (*gnn_node_df) (gnn_node         *node,
                        const gsl_vector *x,
                        const gsl_vector *w,
                        const gsl_vector *dy,
                        gsl_vector       *dxw);

/**
 * @brief gnn_node_destructor type definition.
 * @ingroup gnn_node_ext
 *
 * This is the type for gnn_node's destroy functions.
 * An example function is:
 * \code
 * void
 * my_destroy (gnn_node *node)
 * {
 *     // function implementation
 *     ...
 * }
 * \endcode
 */
typedef void
        (*gnn_node_destructor) (gnn_node *layer);

/**
 * @brief   gnn_node Fundamental Structure.
 * @ingroup gnn_node_ext
 *
 * This structure holds the information for a node.
 *
 * - type: This is a string that holds the name of the node's type.
 *         It allows to check a node's type at runtime.
 * - n: The size of the input vector \f$x\f$.
 * - m: The size of the output vector \f$y\f$.
 * - whnd: The node's own parameter handle.
 * - whnds: This is a NULL-terminated array of \ref gnn_whnd parameter
 *          handles. Every handle appears at most 1 time (i.e.
 *          there aren't any handles pointing to the same parameters).
 * - x: A pointer to the last evaluated input vector \f$x\f$.
 * - destroy: A pointer to the node's destructor, which is invoked
 *            when called the \ref gnn_node_destroy function. It should
 *            free the additional memory allocated for the specific node type.
 * - f: A pointer to the evaluation function, which is called upon execution
 *      of \ref gnn_node_eval_f.
 * - dw: A pointer to the gradient with respect to its parameters
 *       \f$\frac{\partial E}{\partial w_l}\f$, which is called upon execution
 *       of \ref gnn_node_eval_dw.
 * - dx: A pointer to the gradient with respect to its inputs
 *       \f$\frac{\partial E}{\partial x_i}\f$, which is called upon execution
 *       of \ref gnn_node_eval_dw.
 * - super: A pointer to it's parent node (super), or NULL if the node is
 *          the root of the function tree.
 * - nsub: The number of children (subnodes) of the current node.
 * - sub: An array of pointer of size (nsub) with pointers to the current
 *        node's subnodes.
 */
struct _gnn_node
{
    const char       *type;         /**< The layer's type.                   */
    int               n;            /**< The layer's input size \f$n\f$.     */
    int               m;            /**< The layer's output size \f$m\f$.    */
    
    gnn_phandle      *ph;           /**< Pointer to the parameter handle.    */
    gnn_pbundle      *pb;           /**< Parameter bundle.                   */

    gsl_vector  x;                  /**< Last input. */
    gsl_vector  dy;                 /**< Last dy.    */

    gnn_node_destructor destroy;    /**< Destroy function pointer */
    gnn_node_f        f;            /**< Evaluation function \f$F\f$ pointer */
    gnn_node_df       dw;           /**< \f$\frac{\partial E}{\partial W}\f$
                                         function pointer                    */
    gnn_node_df       dx;           /**< \f$\frac{\partial E}{\partial W}\f$
                                         function pointer                    */
                                         
    gnn_node         *super;        /**< Pointer to the supernode.           */
    int               nsub;         /**< Number of subnodes.                 */
    gnn_node        **sub;          /**< Pointer to the subnode array.       */
};



/******************************************/
/* External Typedefs                      */
/******************************************/

#ifndef _GNN_NODE_VECTOR_H_
    #include "gnn_node_vector.h"
#endif



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

/*************/
/* Basic API */
/*************/

int
gnn_node_is_root (gnn_node *node);

const char *
gnn_node_get_type_name (gnn_node *node);

int
gnn_node_input_get_size (gnn_node *node);

int
gnn_node_output_get_size (gnn_node *node);

int
gnn_node_destroy (gnn_node *node);

int
gnn_node_evaluate_init (gnn_node *node);

int
gnn_node_evaluate_f (gnn_node         *node,
                     const gsl_vector *x,
                     gsl_vector       *y);

int
gnn_node_evaluate_dx (gnn_node         *node,
                      const gsl_vector *dy,
                      gsl_vector       *dx);

int
gnn_node_evaluate_dw (gnn_node         *node,
                      gsl_vector       *dw);



/*****************/
/* Parameter API */
/*****************/

int
gnn_node_param_get_size (gnn_node *node);

int
gnn_node_param_get (gnn_node *node, gsl_vector *w);

int
gnn_node_param_set (gnn_node *node, const gsl_vector *w);

int
gnn_node_param_freeze_flags_get (gnn_node *node, gsl_vector_int *f);

int
gnn_node_param_freeze_flags_set (gnn_node *node, const gsl_vector_int *f);

int
gnn_node_param_freeze (gnn_node *node, int i);

int
gnn_node_param_unfreeze (gnn_node *node, int i);

int
gnn_node_param_is_frozen (gnn_node *node, int i);

int
gnn_node_param_are_frozen (gnn_node *node);

int
gnn_node_param_freeze_all (gnn_node *node);

int
gnn_node_param_unfreeze_all (gnn_node *node);

int
gnn_node_param_share (const gnn_node *node, gnn_node *client);



/*****************/
/* Extension API */
/*****************/

int
gnn_node_init (gnn_node           *node,
               const char         *type,
               gnn_node_f          f,
               gnn_node_df         dx,
               gnn_node_df         dw,
               gnn_node_destructor dest);

int
gnn_node_set_sizes (gnn_node *node, int n, int m, int l);

gsl_vector *
gnn_node_local_get_w (gnn_node *node);

gsl_vector *
gnn_node_local_get_dw (gnn_node *node);

gsl_vector_int *
gnn_node_local_get_f (gnn_node *node);

int
gnn_node_local_update (gnn_node *node);

int
gnn_node_eval_f (gnn_node *node, const gsl_vector *x, gsl_vector *y);

int
gnn_node_eval_dx (gnn_node *node, const gsl_vector *dy, gsl_vector *dx);

int
gnn_node_eval_dw (gnn_node *node);



/****************/
/* Subnode API  */
/****************/

int
gnn_node_sub_install_specific (gnn_node *node, int nsub, ...);

int
gnn_node_sub_install (gnn_node *node, int nsub, va_list subs);

int
gnn_node_sub_install_node_vector (gnn_node *node, gnn_node_vector *vector);

int
gnn_node_sub_get_number (gnn_node *node);

gnn_node *
gnn_node_sub_get_node_at (gnn_node *node, int i);

gnn_pbundle *
gnn_node_sub_search_params (gnn_node *node, const char *type);



#endif /* _GNN_NODE_H_ */

---