---

gnn_phandle : A Handle for Parameters.
[gnn_node : Basic Building Block for Gradient Machines.]

---

Detailed Description

The gnn_phandle provides a data structure for encapsulating the necessary information for handling shareable parameters. A gnn_phandle knows about the number of free (not fixed) parameters, its values, and if they are actually used.

The following scheme shows a 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 gnn_phandle_ref and unregister with gnn_phandle_unref.

• 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 gnn_phandle_get_w, gnn_phandle_get_dw and gnn_phandle_get_f respectivelly. After changing them, call gnn_phandle_update. This will update the fields to reflect the changes that have been made.

Also, the gnn_pbundle interface can be used to manipulate a set of related parameter handles.

Warning:

Currently, the handling of parameters isn't thread safe.

Data Structures
struct	gnn_phandle
	The gnn_phandle type. More...
Typedefs
typedef enum _phandle_update	phandle_update
	A type for update flags.
Functions
void	gnn_phandle_destroy (gnn_phandle *ph)
	Destroys a parameter handle.
int	gnn_vector_use_flags (gsl_vector *v, const gsl_vector_int *f)
	Set the frozen parameters to zero.
int	gnn_vector_int_count_frozen_flags (const gsl_vector_int *f)
	Counts the amount of frozen flags.
gnn_phandle *	gnn_phandle_new (size_t size)
	Creates a new parameter handle.
int	gnn_phandle_unref (gnn_phandle *ph)
	Unreferences a parameter handle.
int	gnn_phandle_ref (gnn_phandle *ph)
	References a parameter handle.
size_t	gnn_phandle_get_size (gnn_phandle *ph)
	Returns the total number of parameters.
size_t	gnn_phandle_get_free (gnn_phandle *ph)
	Returns the number of free parameters.
gsl_vector *	gnn_phandle_get_w (gnn_phandle *ph)
	Returns a pointer to the internal parameter vector.
gsl_vector *	gnn_phandle_get_dw (gnn_phandle *ph)
	Returns a pointer to the internal parameter gradient.
gsl_vector_int *	gnn_phandle_get_f (gnn_phandle *ph)
	Returns a pointer to the internal frozen flags.
int	gnn_phandle_update (gnn_phandle *ph)
	Updates the handle's fields.
Variables
chunkallocator *	_phallocator = NULL
	The internal memory chunk allocator for parameter handles.

---

Typedef Documentation

typedef enum _phandle_update phandle_update

This flag type is used for keeping track of the updates that are necessary. Definition at line 48 of file gnn_phandle.h.

---

Function Documentation

void gnn_phandle_destroy (  gnn_phandle *    ph )  [static]

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 gnn_phandle : A Handle for Parameters.) when the reference counter falls to zero. Parameters: ph  The parameter handle to be deallocated. Definition at line 122 of file gnn_phandle.c.

gsl_vector* gnn_phandle_get_dw (  gnn_phandle *    ph )

This function returns a pointer to the internal parameter gradient . The user can modify its values at will. After changes are made, the gnn_phandle : A Handle for Parameters. function should be called to recompute the auxiliary information and reflect the changes. Parameters: ph  The parameter handle to be referenced. Returns: A pointer to the parameter gradient. Definition at line 378 of file gnn_phandle.c.

gsl_vector_int* gnn_phandle_get_f (  gnn_phandle *    ph )

This function returns a pointer to the internal frozen flags . The user can modify its values at will. After changes are made, the gnn_phandle : A Handle for Parameters. 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. Parameters: ph  The parameter handle to be referenced. Returns: A pointer to the frozen flags. Definition at line 404 of file gnn_phandle.c.

size_t gnn_phandle_get_free (  gnn_phandle *    ph )

Parameters: ph  A pointer to a parameter handle. Returns: The number of free (not fixed) parameters. Definition at line 339 of file gnn_phandle.c.

size_t gnn_phandle_get_size (  gnn_phandle *    ph )

Parameters: ph  A pointer to a parameter handle. Returns: The number of total (free + frozen) parameters. Definition at line 325 of file gnn_phandle.c.

gsl_vector* gnn_phandle_get_w (  gnn_phandle *    ph )

This function returns a pointer to the internal parameter vector . The user can modify its values at will. After changes are made, the gnn_phandle : A Handle for Parameters. function should be called to recompute the auxiliary information and reflect the changes. Parameters: ph  The parameter handle to be referenced. Returns: A pointer to the parameter vector. Definition at line 358 of file gnn_phandle.c.

gnn_phandle* gnn_phandle_new (  size_t    size )

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. Parameters: size  The number of parameters that the handle should actually handle. Returns: A pointer to a new parameter handle. Definition at line 219 of file gnn_phandle.c.

int gnn_phandle_ref (  gnn_phandle *    ph )

This function increases the reference count of the parameter handle. It should be called when the parameters are being shared. Parameters: ph  The parameter handle to be referenced. Definition at line 305 of file gnn_phandle.c.

int gnn_phandle_unref (  gnn_phandle *    ph )

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. Parameters: ph  The parameter handle to be unreferenced. Definition at line 279 of file gnn_phandle.c.

int gnn_phandle_update (  gnn_phandle *    ph )

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. Parameters: ph  The parameter handle to be updated. Returns: 0 if succeeded. Definition at line 427 of file gnn_phandle.c.

int gnn_vector_int_count_frozen_flags (  const gsl_vector_int *    f )  [static]

This function takes an integer vector with binary values {0,1} and counts the amount of non-zero values, which correspond to frozen flags. Parameters: f  An integer vector of binary values. Returns: 0 if succeeded. Definition at line 182 of file gnn_phandle.c.

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

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. Parameters: v  A real vector. f  An integer vector of binary values. Returns: 0 if succeeded. Definition at line 152 of file gnn_phandle.c.

---

Variable Documentation

chunkallocator* _phallocator = NULL [static]

This variable points to the parameter handle memory allocator. A first call to gnn_phandle : A Handle for Parameters. instanciates it. Definition at line 87 of file gnn_phandle.c.

---