unh_cmac.h

CMAC Neural Network Code

/* *************************************** */
/*  unh_cmac.h - CMAC function prototypes  */
/* *************************************** */

/* Define some commonly used CMAC receptive fields geometries */

#define	ALBUS			(int)'A'
#define	RECTANGULAR		(int)'R'
#define	LINEAR			(int)'L'
#define	SPLINE			(int)'S'
#define	CUSTOM			(int)'C'

/* ---------------------------------------------------------------------------*/

int allocate_cmac(int num_state,int *qnt_state,
	       int num_resp, int num_cell,
	       int memory, int rfield_shape, int collision_flag);
/*
Returns:    CMAC ID upon success (1-7), 0 upon failure

DESCRIPTION:
This procedure allocates a CMAC with the parameters defined as follows:

      num_state         dimension of the input state vector
      qnt_state[]       quantization vector
      num_resp          dimension of the output response vector
      num_cell          generalization parameter
      memory            number of vectors in the CMAC memory
      rfield_shape      one of the above defined constants for RF functions
      collision_flag    TRUE if collisions OK, FALSE for no collisions
      
The quantization vector is a scalling vector with the same dimension as
the input state vector.  Essentially, in interpretating the state vector the
CMAC routines first divide each component of it with the corresponding
component of the quantization vector.

The procedure returns a number, referred to as the CMAC ID, used in later
calls to identify which CMAC is being accessed.  An ID of 0 indicates that
either the memory allocation failed, or the maximum number of simultaneous
CMACs, set by cmac_init, has been exceeded.
---------------------------------------------------------------------------*/

int train_cmac(int cmac_id, int *state, int *respns, int beta1, int beta2);
/*
Returns:    1 if success, 0 upon failure

DESCRIPTION:
This procedure trains the CMAC memory, where:

     cmac_id  identifies the cmac, (the number returned by alloc_cmac()).
     state    points to the training input state vector.
     respns   points to the training output response vector.
     beta1    is the response error training gain expressed as a right shift
              factor (i.e. 0 = 1.0, 1 = 0.5, 2 = 0.25, ...).
     beta2    is the weight normalization training gain expressed as a right
              shift factor (i.e. 0 = 1.0, 1 = 0.5, 2 = 0.25, ...).

The procedure returns TRUE (1) if completed successfully, FALSE (0) if the
cmac_id is incorrect.
---------------------------------------------------------------------------*/

int cmac_response(int cmac_id, int *state, int *respns);
/*
Returns:    1 if success, 0 upon failure

DESCRIPTION:
This procedure returns the CMAC response, where:

     cmac_id  identifies the cmac, (the number returned by alloc_cmac()).
     state    points to the training input state vector.
     respns   points to the training output response vector.

The procedure returns TRUE (1) if completed successfully, FALSE (0) if the
cmac_id is incorrect.
---------------------------------------------------------------------------*/

int clear_cmac_weights(int cmac_id);
/*
Returns:    1 if success, 0 upon failure

DESCRIPTION:
This procedure clears the CMAC memory to all 0 values (forgets past training)
where cmac_id is the identification number returned by alloc_cmac().
The procedure returns TRUE (1) if completed successfully, FALSE (0) if the
cmac_id is incorrect.
---------------------------------------------------------------------------*/

int deallocate_cmac(int cmac_id);
/*
Returns:    1 if success, 0 upon failure

DESCRIPTION:
This procedure de-allocates the CMAC memory, where cmac_id is the
identification number returned by alloc_cmac().

The procedure returns TRUE (1) if completed successfully, FALSE
(0) if the cmac_id is invalid.
---------------------------------------------------------------------------*/


int cmac_memory_usage(int cmac_id);
/*
Returns:    number of non-zero weight vectors in a CMAC memory

DESCRIPTION:
This procedure returns the number of CMAC memory vectors that
have been used in training since the last call to forget, where cmac_id is 
the identification number returned by alloc_cmac().

The procedure returns FALSE (0) if the identification is incorrect OR if the
memory is all 0's.
---------------------------------------------------------------------------*/

int get_cmac(int cmac_id, int index, int *buffer, int count);
/*
Returns:    number of weight vectors transferred

DESCRIPTION:
This procedure transfers vector values directly from the CMAC memory to
the buffer specified, where:

     cmac_id  is the CMAC identification number.
     index    is a legal index into the CMAC memory (in vector offset
              units, 0 = first vector, 1 = second vector, etc.).
     buffer   is a pointer to a buffer to which the CMAC memory is to
              be transfered.
     count    is the number of sequential vectors to be transfered to
              the buffer.
---------------------------------------------------------------------------*/

int put_cmac(int cmac_id, int index, int *buffer, int count);
/*
Returns:    number of weight vectors transferred

DESCRIPTION:
This procedure transfers vector values directly to the CMAC memory from the
buffer specified, where:

     cmac_id  is the CMAC identification number.
     index    is a legal index into the CMAC memory (in vector offset
              units, 0 = first vector, 1 = second vector, etc.).
     buffer   is a pointer to a buffer from which the CMAC memory is to be
              transfered.
     count    is the number of sequential vectors to be transfered from
              the buffer.

---------------------------------------------------------------------------*/

int adjust_cmac(int cmac_id,int *state,int *drespns,int beta1);

/***************************************************************************
 *      adjust()                                                           *
 *                                                                         *
 *      Input:          cmac_id, state[], drespns[], beta                  *
 *      Output:         ap[]                                               *
 *                                                                         *
 *      Purpose:        Train ap[] cells based on latest experience        *
 *                      state[] is mapped to indexes[] by stoap()          *
 *                                                                         *
 ***************************************************************************
---------------------------------------------------------------------------*/

int map_cmac_input(int cmac_id,int *state,int *weights[], int *rfmags);

/***************************************************************************
 *      map_cmac_input()                                                   *
 *                                                                         *
 *      Input:          cmac_id, state[]                                   *
 *      Output:         *weights[], rfmags[]                               *
 *                                                                         *
 *      Purpose:        returns pointers to the weight vectors mapped      *
 *						by the input vector state[], and the associated    *
 *						receptive field magnitudes                         *
 *                                                                         *
 ***************************************************************************
 ---------------------------------------------------------------------------*/

int set_cmac_rf_displacement(int cmac_id,int *buffer);

/***************************************************************************
 *      set_displacement()                                                 *
 *                                                                         *
 *      Input:          cmac_id, displacement vector                       *
 *      Output:         none                  							   *
 *                                                                         *
 *      Purpose:        writes displacement vector to CMAC storage         *
 *                                                                         *
 ***************************************************************************
---------------------------------------------------------------------------*/

int set_cmac_rf_magnitude(int cmac_id,int *buffer);

/***************************************************************************
 *      set_rf_table()                                                     *
 *                                                                         *
 *      Input:          cmac_id, RF function table                         *
 *      Output:         none                  							   *
 *                                                                         *
 *      Purpose:        writes RF magnitude table to CMAC storage          *
 *                                                                         *
 ***************************************************************************
---------------------------------------------------------------------------*/

int save_cmac(int cmac_id,char *filename);

/***************************************************************************
 *      save_cmac()                                                        *
 *                                                                         *
 *      Input:          cmac_id, file name                                 *
 *      Output:         none                  							   *
 *                                                                         *
 *      Purpose:        writes all of CMAC storage to a file               *
 *                                                                         *
 ***************************************************************************
---------------------------------------------------------------------------*/

int restore_cmac(char *filename);

/***************************************************************************
 *      restore_cmac()                                                     *
 *                                                                         *
 *      Input:          file name                                          *
 *      Output:         cmac_id, or FALSE (0) on failure    			   *
 *                                                                         *
 *      Purpose:        restores all of CMAC storage from a file           *
 *                                                                         *
 ***************************************************************************
---------------------------------------------------------------------------*/