---

gnn_pbundle : A Unified View of Parameter Sets.
[gnn_node : Basic Building Block for Gradient Machines.]

---

Detailed Description

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 gnn_pbundle_new, and more gnn_phandle can be added with gnn_pbundle_insert and removed with gnn_pbundle_remove functions. The bundle keeps track of the amount of times every handle has been added.

A bundle can me augmented with another bundle's element by invoking the gnn_pbundle_join function. To detach elements, use the gnn_pbundle_detach function. Each of this functions keep the multiplicity counters consistent.

By calling the gnn_phandle_get function, you can retrieve the bundle's parameter vector , which is the ordered concatenation of the subparameters of each of the handles:

where is the -th handle's parameter vector. The parameter's total size is gnn_pbundle_get_size.

The specific order in which the handles are stored in the 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 can be accessed and manipulated using a set of provided functions. Similarly, a set of analogous functions is available for the gradient and the frozen flags .

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.

Functions
gnn_pbundle *	gnn_pbundle_new ()
	Creates a new gnn_pbundle.
void	gnn_pbundle_destroy (gnn_pbundle *pb)
	Destroys a gnn_pbundle.
int	gnn_pbundle_insert (gnn_pbundle *pb, gnn_phandle *ph, int n)
	Inserts a parameter handle into a parameter bundle.
int	gnn_pbundle_remove (gnn_pbundle *pb, const gnn_phandle *ph, int n)
	Removes a parameter handle from a parameter bundle.
int	gnn_pbundle_join (gnn_pbundle *pb, const gnn_pbundle *pbop)
	Join two parameter bundles.
int	gnn_pbundle_detach (gnn_pbundle *pb, const gnn_pbundle *pbop)
	Detach a parameter bundle.
int	gnn_pbundle_get_n_free (gnn_pbundle *pb)
	Get the number of free parameters hold by the bundle.
int	gnn_pbundle_get_size (gnn_pbundle *pb)
	Get the size of the parameter hold by the bundle.
int	gnn_pbundle_get_w (gnn_pbundle *pb, gsl_vector *w)
	Get the complete parameter vector.
int	gnn_pbundle_set_w (gnn_pbundle *pb, const gsl_vector *w)
	Set parameter vector.
int	gnn_pbundle_set_w_at (gnn_pbundle *pb, size_t i, double wi)
	Set the i-th parameter.
int	gnn_pbundle_set_w_all (gnn_pbundle *pb, double wi)
	Sets a value for all parameters.
double	gnn_pbundle_get_w_at (gnn_pbundle *pb, size_t i)
	Gets the i-th paramter.
int	gnn_pbundle_get_dw (gnn_pbundle *pb, gsl_vector *dw)
	Gets a the parameter gradient.
int	gnn_pbundle_set_dw (gnn_pbundle *pb, const gsl_vector *dw)
	Sets a the parameter gradient.
int	gnn_pbundle_set_dw_at (gnn_pbundle *pb, size_t i, double dwi)
	Sets the i-th parameter gradient value.
int	gnn_pbundle_set_dw_all (gnn_pbundle *pb, double dwi)
	Sets a unique value for all the parameter gradient's elements.
double	gnn_pbundle_get_dw_at (gnn_pbundle *pb, size_t i)
	Gets the i-th parameter gradient.
int	gnn_pbundle_get_f (gnn_pbundle *pb, gsl_vector_int *f)
	Gets freeze flag vector.
int	gnn_pbundle_set_f (gnn_pbundle *pb, const gsl_vector_int *f)
	Sets the freeze flags.
int	gnn_pbundle_set_f_at (gnn_pbundle *pb, size_t i, int fi)
	Sets the i-th freeze flag.
int	gnn_pbundle_set_f_all (gnn_pbundle *pb, int fi)
	Sets a value for all freeze flags.
int	gnn_pbundle_get_f_at (gnn_pbundle *pb, size_t i)
	Gets the i-th freeze flag.
Variables
chunkallocator *	_ca = NULL
	The internal gnn_pbundle memory chunk allocator.

---

Function Documentation

void gnn_pbundle_destroy (  gnn_pbundle *    pb )

This function destroys a given gnn_pbundle by deallocating its memory and by unreferencing the contained parameter handles. Returns: A pointer to the new gnn_pbundle of NULL if failed. Definition at line 155 of file gnn_pbundle.c.

int gnn_pbundle_detach (  gnn_pbundle *    pb, const gnn_pbundle *    pbop )

This function removes the parameter bundle "pbop" from "pb", respecting the multiplicity of each element. Parameters: pb  A parameter bundle. pbop  A parameter bundle. Returns: 0 if suceeded. Definition at line 325 of file gnn_pbundle.c.

int gnn_pbundle_get_dw (  gnn_pbundle *    pb, gsl_vector *    dw )

This function fills the vector dw with the parameter gradient values of the parameter bundle. The frozen flags are respected. Parameters: pb  A parameter bundle. dw  A sufficiently large vector to be filled. Returns: 0 if succeeded. Definition at line 611 of file gnn_pbundle.c.

double gnn_pbundle_get_dw_at (  gnn_pbundle *    pb, size_t    i )

This function returns the i-th parameter gradient, respecting its frozen flag. Parameters: pb  A parameter bundle. i  Index of the parameter gradient to be retrieved. Returns: The i-th parameter gradient. Definition at line 791 of file gnn_pbundle.c.

int gnn_pbundle_get_f (  gnn_pbundle *    pb, gsl_vector_int *    f )

Parameters: pb  A parameter bundle. f  A buffer vector to be filled with the freeze flags of the correct size. Returns: 0 if succeeded. Definition at line 830 of file gnn_pbundle.c.

int gnn_pbundle_get_f_at (  gnn_pbundle *    pb, size_t    i )

Parameters: pb  A parameter bundle. i  The indexof the freeze flag to be returned. Returns: 0 if the i-th parameter is free or 1 if frozen. Definition at line 1007 of file gnn_pbundle.c.

int gnn_pbundle_get_n_free (  gnn_pbundle *    pb )

This function returns the number of free parameters that the bundle manages. Parameters: pb  A paramter bundle. Returns: The number of free parameters. Definition at line 353 of file gnn_pbundle.c.

int gnn_pbundle_get_size (  gnn_pbundle *    pb )

This function returns the number of parameters that the bundle manages. Parameters: pb  A paramter bundle. Returns: The number of total parameters. Definition at line 382 of file gnn_pbundle.c.

int gnn_pbundle_get_w (  gnn_pbundle *    pb, gsl_vector *    w )

This function fills the given real vector with the parameter bundles parameters. Parameters: pb  A parameter bundle. w  A real vector of the correct size. Returns: 0 if succeeded. Definition at line 415 of file gnn_pbundle.c.

double gnn_pbundle_get_w_at (  gnn_pbundle *    pb, size_t    i )

Parameters: pb  A parameter bundle. i  The index of the parameter to be retrieved. Returns: The value of the i-th parameter. Definition at line 572 of file gnn_pbundle.c.

int gnn_pbundle_insert (  gnn_pbundle *    pb, gnn_phandle *    ph, int    n )

This function takes a parameter bundle and a parameter handle as arguments. It creates a new 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. Parameters: pb  A parameter bundle. ph  A parameter handle. n  The multiplicity of the handle. Returns: 0 if succeeded. Definition at line 193 of file gnn_pbundle.c.

int gnn_pbundle_join (  gnn_pbundle *    pb, const gnn_pbundle *    pbop )

This function increases the parameter bundle "pb" with "pbop"'s elements without changing the "pbop" bundle. Parameters: pb  A parameter bundle. pbop  A parameter bundle. Returns: 0 if suceeded. Definition at line 295 of file gnn_pbundle.c.

gnn_pbundle* gnn_pbundle_new (    )

This function allocates a new gnn_pbundle with its values initialized to zero parameter handles / elements. Implementation Note: The memory is managed (for efficiency) by a memory chunk allocator. Returns: A pointer to the new gnn_pbundle of NULL if failed. Definition at line 123 of file gnn_pbundle.c.

int gnn_pbundle_remove (  gnn_pbundle *    pb, const gnn_phandle *    ph, int    n )

This function takes a parameter bundle and a parameter handle as arguments. It removes "n" copies of the given parameter handle from the bundle. Parameters: pb  A parameter bundle. ph  A parameter handle. Returns: 0 if succeeded. Definition at line 246 of file gnn_pbundle.c.

int gnn_pbundle_set_dw (  gnn_pbundle *    pb, const gsl_vector *    dw )

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). Parameters: pb  A parameter bundle. dw  The values for the parameter gradient. Returns: 0 if succeeded. Definition at line 665 of file gnn_pbundle.c.

int gnn_pbundle_set_dw_all (  gnn_pbundle *    pb, double    dwi )

This function fills the vector dw with the value given as dwi. The frozen flags are respected. Parameters: pb  A parameter bundle. dwi  The new value for the parameter. Returns: 0 if succeeded. Definition at line 757 of file gnn_pbundle.c.

int gnn_pbundle_set_dw_at (  gnn_pbundle *    pb, size_t    i, double    dwi )

This function sets the value of the parameter gradient's i-th element. The frozen flags are respected. Parameters: pb  A parameter bundle. i  The index of the value to be set. dwi  The new value for the parameter gradient. Returns: 0 if succeeded. Definition at line 719 of file gnn_pbundle.c.

int gnn_pbundle_set_f (  gnn_pbundle *    pb, const gsl_vector_int *    f )

This function fills freeze flags vector with the binary {0,1} values given in the integer vector f. Parameters: pb  A parameter bundle. f  A integer vector with binary values. Returns: 0 if succeeded. Definition at line 881 of file gnn_pbundle.c.

int gnn_pbundle_set_f_all (  gnn_pbundle *    pb, int    fi )

This function fills the freeze flag vector with the value given a parameter. Parameters: pb  A parameter bundle. fi  The new value for all freeze flags. It should be 0 (free) or 1 (frozen). Returns: 0 if succeeded. Definition at line 975 of file gnn_pbundle.c.

int gnn_pbundle_set_f_at (  gnn_pbundle *    pb, size_t    i, int    fi )

Parameters: pb  A parameter bundle. i  The index of the freeze flag to be set. fi  The value (0=free or 1=frozen) of the flag. Returns: 0 if succeeded. Definition at line 934 of file gnn_pbundle.c.

int gnn_pbundle_set_w (  gnn_pbundle *    pb, const gsl_vector *    w )

This function takes fills the parameter bundle with the values given in the real vector w. Parameters: pb  A pointer to a parameter bundle. w  A pointer to a real vector. Returns: 0 if succeeded. Definition at line 464 of file gnn_pbundle.c.

int gnn_pbundle_set_w_all (  gnn_pbundle *    pb, double    wi )

Parameters: pb  A parameter bundle. wi  The new value for the parameter. Returns: 0 if succeeded. Definition at line 545 of file gnn_pbundle.c.

int gnn_pbundle_set_w_at (  gnn_pbundle *    pb, size_t    i, double    wi )

Parameters: pb  A parameter bundle. i  The index of the parameter to be set. wi  The new value for the parameter. Returns: 0 if succeeded. Definition at line 511 of file gnn_pbundle.c.

---

Variable Documentation

chunkallocator* _ca = NULL [static]

This static variable holds the internal memory chunk allocator for the 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. Definition at line 102 of file gnn_pbundle.c.

---